docs: adds additional examples to functions

docs/components/FunctionReference.vue

@@ -1,16 +1,8 @@
 <script lang="ts" setup>
-const props = withDefaults(
-  defineProps<{
-    function: string
-    arguments: Array<{ name: string; type: string; comment?: string }>
-    overload?: Array<{ name: string; type: string; comment?: string }>
-    return: string
-    wrapper?: boolean
-  }>(),
-  {
-    wrapper: true,
-  }
-)
+import type { FunctionRef } from "../src/types"
+const props = withDefaults(defineProps<FunctionRef>(), {
+  wrapper: true,
+})
 </script>
 
 <template>

docs/components/ObjectReference.vue

@@ -1,5 +1,5 @@
 <script lang="ts" setup>
-const props = defineProps<{
+defineProps<{
   type: string
   properties: { name: string; type: string; jsdoc: string[] }[]
 }>()

docs/components/content/Format.vue

@@ -319,11 +319,77 @@ import { format } from "@formkit/tempo"
       </tbody>
     </table>
     <CodeExample file="format-tokens" />
+    <h4>Format options</h4>
     <p>
-      The <code>format()</code> function accepts a fourth argument, a boolean
-      indicating whether or not genitive cases should be used. This is useful
-      for languages that have different forms of the month and day names when
-      used in a context that requires the genitive case.
+      The <code>format()</code> function can accept an object of options as its
+      argument to provide more control over the output.
+    </p>
+    <ObjectReference
+      type="FormatOptions"
+      :properties="[
+        {
+          name: 'date',
+          type: 'string | Date',
+          jsdoc: ['An ISO 8601 date string or a Date object.'],
+        },
+        {
+          name: 'format',
+          type: 'string | { date?: string, time?: string }',
+          jsdoc: ['The format can be either format styles or format tokens.'],
+        },
+        {
+          name: 'locale?',
+          type: 'string',
+          jsdoc: ['The locale to use when formatting.'],
+        },
+        {
+          name: 'tz?',
+          type: 'string',
+          jsdoc: [
+            'Converts the given date option to the timezone provided.',
+            'For example, if the provided date option is 2021-01-01T00:00:00Z',
+            'and the tz option is America/New_York and the format option is',
+            'YYYY-MM-DD HH:mm:ss, the output will be 2020-12-31 19:00:00',
+          ],
+        },
+        {
+          name: 'genitive?',
+          type: 'boolean',
+          jsdoc: [
+            'When true, the month and weekday names will be in the',
+            'genitive case for locales where it is applicable.',
+          ],
+        },
+        {
+          name: 'partFilter?',
+          type: '(part: Part) => boolean',
+          jsdoc: [
+            'A function that filters the parts of the formatted date.',
+            'The function is called with each part of the formatted date',
+            'and should return true to include the part in the output.',
+          ],
+        },
+      ]"
+    />
+    <h4>Timezone</h4>
+    <p>
+      The <code>tz</code> option allows you to format the provided date from the
+      perspective of any given timezone.
+    </p>
+    [CODE EXAMPLE HERE]
+    <h4>Part filter</h4>
+    <p>
+      The <code>partFilter</code> option allows you to filter out parts of the
+      formatted date. The function is called with each "part" of the formatted
+      date and should return a boolean indicating whether or not to include that
+      part in final formatted string.
+    </p>
+    [CODE EXAMPLE HERE]
+    <h4>Genitive case</h4>
+    <p>
+      Some languages have a genitive case for months and weekdays. When the
+      genitive option is set to true, the month and weekday names will be in the
+      genitive case for locales where it is applicable.
     </p>
     <CodeExample file="format-genitive" />
   </PageSection>

docs/components/content/Modify.vue

@@ -1,5 +1,14 @@
 <script lang="ts" setup>
-const fns = {
+import type { FunctionRef } from "../../src/types"
+const fns: Record<
+  string,
+  {
+    description: string
+    return: string
+    arguments: FunctionRef["arguments"]
+    example?: string
+  }
+> = {
   addDay: {
     description:
       "Returns a new Date object with a positive or negative number of days applied to date argument. To subtract days, use a negative number.",
@@ -14,6 +23,7 @@ const fns = {
         type: "number",
       },
     ],
+    example: "addDay",
   },
   addHour: {
     description:
@@ -126,6 +136,18 @@ const fns = {
         comment: "+-HHmm, ex: -0800",
       },
     ],
+    example: "applyOffset",
+  },
+  date: {
+    description: `Converts an ISO 8601 like string into a Date object (noop on <code>Date</code> objects). ISO 8601 strings do not need to be complete to be accepted, but you need at least a year and month.`,
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+    ],
+    example: "date",
   },
   dayStart: {
     description: `Returns a new Date object with the time set to 00:00:00.000 (local time).`,
@@ -136,6 +158,7 @@ const fns = {
         type: "string | Date",
       },
     ],
+    example: "dayStart",
   },
   dayEnd: {
     description: `Returns a new Date object with the time set to 23:59:59 (local).`,
@@ -182,6 +205,22 @@ const fns = {
       },
     ],
   },
+  tzDate: {
+    description: `Converts an ISO 8601 like string into a Date object with a timezone applied. For example, <code>tzDate('2021-01-01T00:00:00.000', 'America/Los_Angeles')</code> will return a Date object representing 2021-01-01 00:00:00 in L.A. which equates to <code>2021-01-01T00:00:00.000</code>.`,
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+      {
+        name: "tz",
+        type: "string",
+        comment: 'IANA timezone, ex: "America/Los_Angeles"',
+      },
+    ],
+    example: "tzDate",
+  },
   weekStart: {
     description: `Returns a new Date object with the date set to the first day of the current week with the time set to 00:00:00 (local).`,
     return: "Date",
@@ -226,12 +265,13 @@ const fns = {
     </p>
     <div v-for="(def, fn) in fns">
       <h4>{{ fn }}</h4>
-      <p v-html="def.description" />
       <FunctionReference
         :function="fn"
         :arguments="def.arguments"
         :return="def.return"
       />
+      <p v-html="def.description" />
+      <CodeExample v-if="def.example" :file="def.example" />
     </div>
   </PageSection>
 </template>

docs/examples/addDay.ts

@@ -0,0 +1,9 @@
+import { addDay } from "@formkit/tempo"
+
+// Add 1 day
+addDay("2013-03-15")
+// Add 5 days
+addDay("2013-03-15", 5)
+
+// Subtract 3 days
+addDay("2013-03-15", -3)

docs/examples/date.ts

@@ -0,0 +1,4 @@
+import { date } from "@formkit/tempo"
+
+// Partial ISO 8601 strings are acceptable
+date("2013-11")

docs/examples/dayStart.ts

@@ -0,0 +1,3 @@
+import { dayStart } from "@formkit/tempo"
+
+dayStart("2013-07-30T12:00:00Z")

docs/examples/format-genitive.ts

@@ -3,6 +3,11 @@ import { format } from "@formkit/tempo"
 const t = "2013-03-15"
 
 // The month name
-format(t, "MMMM", "ru")
+format({ date: t, format: "MMMM", locale: "ru" })
 // The genitive form of the month name
-format(t, "MMMM", "ru", true)
+format({
+  date: t,
+  format: "MMMM",
+  locale: "ru",
+  genitive: true,
+})

docs/examples/tzDate.ts

@@ -0,0 +1,4 @@
+import { tzDate } from "@formkit/tempo"
+
+// Produces the date for 12 noon Nov 18, 2013 in New York
+tzDate("2013-11-18 12:00", "America/New_York")

docs/package.json

@@ -20,7 +20,7 @@
   },
   "dependencies": {
     "@formkit/auto-animate": "^0.8.1",
-    "@formkit/tempo": "0.0.2",
+    "@formkit/tempo": "0.0.3",
     "monaco-editor": "^0.40.0"
   }
 }

docs/src/types.ts

@@ -0,0 +1,7 @@
+export type FunctionRef = {
+  function: string
+  arguments: Array<{ name: string; type: string; comment?: string }>
+  overload?: Array<{ name: string; type: string; comment?: string }>
+  return: string
+  wrapper?: boolean
+}

src/format.ts

@@ -40,7 +40,9 @@ export function format(options: FormatOptions): string
 export function format(
   inputDate: DateInput,
   format?: Format,
-  locale?: string
+  locale?: string,
+  genitive?: boolean,
+  partFilter?: (part: Part) => boolean
 ): string
 export function format(
   inputDateOrOptions: DateInput | FormatOptions,

src/index.ts

@@ -7,6 +7,7 @@ export { addSecond } from "./addSecond"
 export { ap } from "./ap"
 export { applyOffset } from "./applyOffset"
 export { date } from "./date"
+export { tzDate } from "./tzDate"
 export { dayOfYear } from "./dayOfYear"
 export { dayEnd } from "./dayEnd"
 export { dayStart } from "./dayStart"

src/types.ts

@@ -153,11 +153,11 @@ export interface FormatOptions {
   /**
    * A locale or en by default.
    */
-  locale?: "en"
+  locale?: string
   /**
    * Whether or not to escape literals.
    */
-  genitive?: false
+  genitive?: boolean
   /**
    * A function to filter parts.
    */