feat(ics): deprecates download() method #196

Removes all Safari-specific code for downloading ICS files. Deprecates
the download method.

README.md

@@ -126,10 +126,10 @@ This will [add the `CATEGORIES` ICS property](https://datebook.dev/api/icalendar
 ##### Downloading
 
 ```ts
-icalendar.download()
+icalendar.render()
 ```
 
-This will [download](https://datebook.dev/api/icalendar.html#download) `Happy Hour.ics` onto the user's device. On most mobile devices, this will open the default calendar app with the event.
+This will render ICS file content that could be [downloaded for use in iCalendar apps](https://datebook.dev/downloading).
 
 #### Google Calendar
 
@@ -144,11 +144,3 @@ googleCalendar.render()
 ```
 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.
-
-| <img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_128x128.png?raw=true" width="48px" height="48px" alt="Chrome logo"> | <img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_128x128.png?raw=true" width="48px" height="48px" alt="Firefox logo"> | <img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/archive/internet-explorer_9-11/internet-explorer_9-11_128x128.png" width="48px" height="48px" alt="Internet Explorer logo"> | <img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_128x128.png" width="48px" height="48px" alt="Edge Browser Logo" > | <img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/opera/opera_128x128.png?raw=true" width="48px" height="48px" alt="Opera logo"> | <img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_128x128.png?raw=true" width="48px" height="48px" alt="Safari logo">
-|:---:|:---:|:---:|:---:|:---:|:---:|
-| Yes ✅ | 20+ ✅ | 11+ ✅ | Yes ✅ | 15+ ✅ | 10.1+ ✅

docs/.vuepress/components/Generator.vue

@@ -57,7 +57,7 @@
 
     <div>
       <h3>iCalendar</h3>
-      <a @click="ics.download()">
+      <a @click="download">
         Download <code>.ics</code> file ↓
       </a>
       <div class="language-typescript">
@@ -75,6 +75,7 @@
 </template>
 
 <script lang="ts">
+import * as FileSaver from 'file-saver'
 import { defineComponent, computed, ref } from 'vue'
 import GoogleCalendar from '../../../src/GoogleCalendar'
 import YahooCalendar from '../../../src/YahooCalendar'
@@ -127,13 +128,22 @@ export default defineComponent({
         : undefined
     }
 
+    function download () {
+      const blob = new Blob([ics.value.render()], {
+        type: 'text/calendar'
+      })
+
+      FileSaver.saveAs(blob, 'Event.ics')
+    }
+
     return {
       isAllDay,
       isRecurring,
       model,
       serviceUrls,
       ics,
-      onRecurrenceChange
+      onRecurrenceChange,
+      download
     }
   }
 })

docs/.vuepress/config.ts

@@ -30,7 +30,7 @@ export default defineUserConfig({
     logo: '/assets/logo.svg',
     repo: 'jshor/datebook',
     docsDir: 'docs',
-    sidebarDepth: 3,
+    sidebarDepth: 4,
     navbar: [
       {
         text: 'Getting started',

docs/README.md

@@ -13,11 +13,11 @@ footer: © 2023 Datebook.
   </div>
   <div class="feature">
     <h2>Major Apps Supported</h2>
-    <p>Fully supports .ics files for iCalendar and Office Outlook, and also supports Google Calendar, Yahoo! Calendar and Outlook Web.</p>
+    <p>Fully supports ICS content generation for iCalendar and Office Outlook, and also supports Google Calendar, Yahoo! Calendar and Outlook Web.</p>
   </div>
   <div class="feature">
-    <h2>No Server Needed</h2>
-    <p>Datebook will generate downloadable iCalendar files on the fly, and URLs contain event data in their query strings.</p>
+    <h2>Consistent and Versatile</h2>
+    <p>The unified API and configuration simplifies the process of rendering URLs and ICS for identical events across calendar providers.</p>
   </div>
 </div>
 
@@ -30,9 +30,9 @@ yarn add datebook
 ### Example usage
 
 ```ts
-import { ICalendar } from 'datebook'
+import { GoogleCalendar } from 'datebook'
 
-const icalendar = new ICalendar({
+const googleCalendar = new GoogleCalendar({
   title: 'Happy Hour',
   location: 'The Bar, New York, NY',
   description: 'Let\'s blow off some steam from our weekly deployments to enjoy a tall cold one!',
@@ -44,5 +44,5 @@ const icalendar = new ICalendar({
   }
 })
 
-icalendar.download()
+window.location.href = googleCalendar.render()
 ```

docs/api/icalendar.md

@@ -58,7 +58,8 @@ Adds an alarm. Multiple different alarms may be added to a single instance. Retu
 const alarm1: Alarm = {
   action: 'DISPLAY',
   trigger: new Date('1998-01-01T05:00:00Z'),
-  description: 'the event description',
+  description: 'The first alarm description',
+  summary: 'The first alarm summary',
   summary: 'a quick summary',
   duration: {
     after: true,
@@ -68,8 +69,14 @@ const alarm1: Alarm = {
 
 const alarm2: Alarm = {
   action: 'DISPLAY',
+  description: 'The second alarm description',
+  summary: 'The second alarm summary',
   trigger: {
     minutes: 5
+  },
+  duration: {
+    after: true,
+    minutes: 3
   }
 }
 
@@ -93,22 +100,25 @@ LOCATION:The Bar, New York, NY
 SUMMARY:Happy Hour
 BEGIN:VALARM
 ACTION:DISPLAY
-DESCRIPTION:the event description
-SUMMARY:a quick summary
+DESCRIPTION:The first alarm description
+SUMMARY:The first alarm summary
 DURATION:PT3M
 TRIGGER;VALUE=DATE-TIME:19980101T050000Z
 END:VALARM
 BEGIN:VALARM
 ACTION:DISPLAY
+DESCRIPTION:The second alarm description
+SUMMARY:The second alarm summary
 DURATION:
 TRIGGER:-PT5M
+DURATION:PT3M
 END:VALARM
 TRANSP:TRANSPARENT
-END:VEVENT
-END:VCALENDAR
 UID:19hq3v1lm15
-DTSTAMP:20200916
+DTSTAMP:20200916T000000
+END:VEVENT
 PRODID:datebook.dev
+END:VCALENDAR
 ```
 
 ## `setMeta(key: string, value: string)` <Badge text="6.0.0" vertical="middle" />
@@ -156,11 +166,11 @@ LOCATION:The Bar, New York, NY
 SUMMARY:Happy Hour
 TRANSP:TRANSPARENT
 CATEGORIES:RECREATION,TEAM-BUILDING
-END:VEVENT
-END:VCALENDAR
 UID:19hq3v1lm15
-DTSTAMP:20200916
+DTSTAMP:20200916T000000
+END:VEVENT
 PRODID:datebook.dev
+END:VCALENDAR
 ```
 
 ## `render()`
@@ -185,15 +195,34 @@ LOCATION:The Bar, New York, NY
 SUMMARY:Happy Hour
 TRANSP:TRANSPARENT
 RRULE:FREQ=DAILY;INTERVAL=1
-END:VEVENT
-END:VCALENDAR
 UID:19hq3v1lm15
-DTSTAMP:20200916
+DTSTAMP:20200916T000000
+END:VEVENT
 PRODID:datebook.dev
+END:VCALENDAR
+```
+
+### Example for downloading an ICS file
+
+Once an ICS file string is rendered, you can use [FileSaver.js](https://www.npmjs.com/package/file-saver) or a similar library to locally download the ICS file onto the user's device.
+
+```ts
+import * as FileSaver from 'file-saver'
+
+const ics = calendar.render()
+const blob = new Blob([ics], {
+  type: 'text/calendar'
+})
+
+FileSaver.saveAs(blob, 'my-calendar-event.ics')
 ```
 
-## `download(fileName?: string)`
+## `download(fileName?: string)` <Badge text="Deprecated" type="warning" vertical="middle" />
 
 * **`fileName: string`** - optional file name
 
 Downloads a `.ics` file on the user's browser for use in local calendars and email clients.
+
+:::warning Deprecation Notice
+This feature is deprecated as of v8 and will be removed in v9.
+:::

docs/start.md

@@ -32,7 +32,7 @@ const config: CalendarOptions = {
 ```ts
 const icalendar = new ICalendar(config)
 
-icalendar.download()
+fs.writeFileSync('my-event.ics', icalendar.render())
 ```
 
 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.
@@ -44,7 +44,7 @@ import { GoogleCalendar } from 'datebook'
 
 const googleCalendar = new GoogleCalendar(config)
 
-googleCalendar.render()
+window.location.href = googleCalendar.render()
 ```
 
 `googleCalendar.render()` will return a URL that the user can navigate to and pre-fill event details:
@@ -67,7 +67,7 @@ Datebook can also be used via script import. CDNs such as [jsdelivr](https://www
   </head>
   <body>
     <script>
-      const ical = new datebook.ICalendar({
+      const googleCalendar = new datebook.GoogleCalendar({
         title: 'Happy Hour',
         location: 'The Bar, New York, NY',
         description: 'Let\'s blow off some steam with a tall cold one!',
@@ -80,7 +80,7 @@ Datebook can also be used via script import. CDNs such as [jsdelivr](https://www
         }
       })
 
-      ical.download()
+      window.location.href = googleCalendar.render()
     </script>
   </body>
 </html>

jest.config.ts

@@ -2,17 +2,19 @@ export default {
   collectCoverage: true,
   collectCoverageFrom: [
     '<rootDir>/src/**/*.ts',
+    '!<rootDir>/src/**/*.d.ts',
     '!<rootDir>/src/index.ts'
   ],
   coverageDirectory: '<rootDir>/coverage',
   coverageThreshold: {
     global: {
-      branches: 88,
+      branches: 90,
       functions: 90,
       lines: 90,
       statements: 90
     }
   },
+  testEnvironment: 'jsdom',
   testMatch: [
     '<rootDir>/src/**/*.spec.ts'
   ],

package.json

@@ -48,9 +48,11 @@
     "eslint": "^8.28.0",
     "husky": "^8.0.2",
     "jest": "^29.3.1",
+    "jest-environment-jsdom": "^29.3.1",
     "query-string": "^7.1.1",
     "standard-version": "^9.5.0",
     "ts-jest": "^29.0.3",
+    "ts-node": "^10.9.1",
     "vuepress": "^2.0.0-beta.53"
   }
 }

src/ICalendar.ts

@@ -10,7 +10,7 @@ import ICSDuration from './types/ICSDuration'
 import ICSPropertyValue from './types/ICSPropertyValue'
 
 /**
- * Generates a downloadable ICS file.
+ * Renders ICS file content.
  */
 export default class ICalendar extends CalendarBase {
   /** List of additional ICalendar events to add. */
@@ -206,11 +206,16 @@ export default class ICalendar extends CalendarBase {
   /**
    * Downloads the rendered iCalendar.
    *
+   * @deprecated This method will be removed in the next major release. See {@link https://datebook.dev/api/icalendar.html#example-for-downloading-an-ics-file}.
    * @remark Only works in browsers.
-   *
    * @param {string} fileName optional explicit file name, if not provided then will be constructed from title
    */
   public download = (fileName?: string): void => {
+    console.warn([
+      'ICalendar.download() is deprecated and will be removed in the next major release.',
+      'See https://datebook.dev/api/icalendar.html#example-for-downloading-an-ics-file for more info on how to download ICS files.'
+    ].join(' '))
+
     ics.download(fileName || ics.getFileName(this.title), this.render())
   }
 

src/index.ts

@@ -1,8 +1,3 @@
-import GoogleCalendar from './GoogleCalendar'
-import YahooCalendar from './YahooCalendar'
-import OutlookCalendar from './OutlookCalendar'
-import ICalendar from './ICalendar'
-
 export { default as CalendarBase } from './CalendarBase'
 export { default as GoogleCalendar } from './GoogleCalendar'
 export { default as YahooCalendar } from './YahooCalendar'
@@ -14,10 +9,3 @@ export { default as ICSAlarm } from './types/ICSAlarm'
 export { default as ICSAttachment } from './types/ICSAttachment'
 export { default as ICSDuration } from './types/ICSDuration'
 export { default as ICSPropertyValue } from './types/ICSPropertyValue'
-
-window.datebook = {
-  GoogleCalendar,
-  YahooCalendar,
-  OutlookCalendar,
-  ICalendar
-}