sanity-plugin-recurring-dates 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Tom Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# sanity-plugin-recurring-dates
+
+> This is a **Sanity Studio v3** plugin.
+
+This is a plugin to add a custom input component to your Sanity Studio which allows you to specify recurring dates.
+
+The plugin allows for easy selection of common recurrences, as well as configuring custom recurrences. It's also possible to provide an end to a recurrence by setting an end date or a count of how many times the recurrnce should happen.
+
+## Installation
+
+```sh
+npm install sanity-plugin-recurring-dates
+```
+
+## Usage
+
+Add it as a plugin in `sanity.config.ts` (or .js):
+
+```ts
+import {defineConfig} from 'sanity'
+import {recurringDates} from 'sanity-plugin-recurring-dates'
+
+export default defineConfig({
+  //...
+  plugins: [recurringDates()],
+})
+```
+
+In your schema, you can then set a field to use the `recurringDates` field type:
+
+```ts
+defineField({
+  name: 'date',
+  title: 'Date',
+  type: 'recurringDates',
+})
+```
+
+## Configuring the plugin
+
+You can configure the plugin on the plugin or field level. Plugin level configuration can be overridden on each field.
+
+### Plugin config
+
+```ts
+export default defineConfig({
+  //...
+  plugins: [
+    recurringDates({
+      // An array of RRULE strings to use as default recurrences
+      defaultRecurrences: [
+        'RRULE:FREQ=DAILY;INTERVAL=1',
+        'RRULE:FREQ=WEEKLY;INTERVAL=1',
+        'RRULE:FREQ=MONTHLY;INTERVAL=1',
+        'RRULE:FREQ=YEARLY;INTERVAL=1',
+      ],
+
+      // Hides the end date field
+      hideEndDate: true, // defaults to false
+
+      // Hides the custom recurrence options
+      hideCustom: true, // defaults to false
+
+      // Configure the datepickers
+      // See https://www.sanity.io/docs/datetime-type#options
+      dateTimeOptions: {
+        dateFormat: 'DD/MM/yyyy',
+        timeFormat: 'HH:mm',
+        timeStep: 15,
+      },
+    }),
+  ],
+})
+```
+
+### Field config
+
+```ts
+defineField({
+  name: 'date',
+  title: 'Date',
+  type: 'recurringDates',
+  options: {
+    // An array of RRULE strings to use as default recurrences
+    defaultRecurrences: [
+      'RRULE:FREQ=DAILY;INTERVAL=1',
+      'RRULE:FREQ=WEEKLY;INTERVAL=1',
+      'RRULE:FREQ=MONTHLY;INTERVAL=1',
+      'RRULE:FREQ=YEARLY;INTERVAL=1',
+    ],
+
+    // Hides the end date field
+    hideEndDate: true, // defaults to false
+
+    // Hides the custom recurrence options
+    hideCustom: true, // defaults to false
+
+    // Configure the datepickers
+    // See https://www.sanity.io/docs/datetime-type#options
+    dateTimeOptions: {
+      dateFormat: 'DD/MM/yyyy',
+      timeFormat: 'HH:mm',
+      timeStep: 15,
+    },
+  },
+})
+```
+
+## Content
+
+Here is an example of the data stored on the field after configuring a recurring date:
+
+```json
+{
+  "rrule": "RRULE:FREQ=MONTHLY;INTERVAL=1;BYDAY=+1MO",
+  "startDate": "2023-08-01T12:47:00.000Z",
+  "endDate": "2023-08-01T15:15:00.000Z"
+}
+```
+
+As the plugin uses the standard Sanity `datetime` field type, the start and end dates are stored in UTC. The `rrule` string is in line with the recurrence rules defined in the [iCalendar RFC](https://tools.ietf.org/html/rfc5545), with rules generated by the [rrule.js](https://github.com/jakubroztocil/rrule) library.
+
+### Using the rules on a frontend
+
+Whilst displaying the recurring dates on a frontend is beyond the scope of this plugin, there are a couple of considerations worth calling out.
+
+As the start dates are stored in UTC, which is a "floating" time, you need to process these into the timezone you want to display the dates in. You'll also need to think about Daylight Saving Time (DST) in these timezones.
+
+By using the `rrule` and `date-fns-tz` libraries, you can achieve this in a similar manner to the below:
+
+```ts
+import {rrulestr} from 'rrule'
+import {formatInTimeZone, getTimezoneOffset} from 'date-fns-tz'
+
+// your desired timezone
+const timezone = 'Europe/London'
+
+// Pass your rrule and startDate to the `rrulestr` function
+const upcomingRule = rrulestr(rrule, {
+  dtstart: startDate,
+})
+
+// Calculate the offset from UTC for your timezone at the start date
+const initialOffset = getTimezoneOffset(timezone, new Date(startDate))
+
+// Map through all the rules, returning an array of dates in the correct timezone
+// with consideration for changes in timezone offset as a result of DST
+const allDates = rule.all().map((date) => {
+  // Calculate the offset from UTC for your timezone at this recurrence
+  const dateOffset = getTimezoneOffset(timezone, date)
+
+  // Calculate the difference between the initial offset and this offset
+  const diff = initialOffset - dateOffset
+
+  // Adjust the date by the difference
+  date.setTime(date.getTime() + diff)
+
+  // Return a formatted date from the date needed, with the format we pass
+  // in the third parameter
+  return formatInTimeZone(
+    date.setTime(date.getTime() + diff),
+    timezone,
+    'EEEE, MMMM d, yyyy h:mm aaaa',
+  )
+})
+```
+
+## License
+
+[MIT](LICENSE) © Tom Smith
+
+## Develop & test
+
+This plugin uses [@sanity/plugin-kit](https://github.com/sanity-io/plugin-kit)
+with default configuration for build & watch scripts.
+
+See [Testing a plugin in Sanity Studio](https://github.com/sanity-io/plugin-kit#testing-a-plugin-in-sanity-studio)
+on how to run this plugin with hotreload in the studio.
+
+
+### Release new version
+
+Run ["CI & Release" workflow](https://github.com/thebiggianthead/sanity-plugin-recurring-dates/actions/workflows/main.yml).
+Make sure to select the main branch and check "Release new version".
+
+Semantic release will only release on configured branches, so it is safe to run release on any branch.

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import type {DatetimeOptions} from 'sanity'
+import type {ObjectDefinition} from 'sanity'
+import {Plugin as Plugin_2} from 'sanity'
+
+export declare interface PluginConfig {
+  defaultRecurrences?: string[]
+  hideEndDate?: boolean
+  hideCustom?: boolean
+  dateTimeOptions?: DatetimeOptions
+}
+
+export declare type RecurringDateFieldOptions = Omit<ObjectDefinition, 'type' | 'fields'> & {
+  type: 'recurringDates'
+  options?: PluginConfig
+}
+
+export declare const recurringDates: Plugin_2<PluginConfig>
+
+export declare type WithRequiredProperty<Type, Key extends keyof Type> = Type & {
+  [Property in Key]-?: Type[Property]
+}
+
+export {}
+
+declare module 'sanity' {
+  interface IntrinsicDefinitions {
+    recurringDates: RecurringDateFieldOptions
+  }
+}