docs: adds tiemzone docs

docs/assets/css/main.css

@@ -2,6 +2,10 @@
 @tailwind components;
 @tailwind utilities;
 
+html {
+  @apply scroll-smooth;
+}
+
 body {
   @apply bg-body;
 }
@@ -28,11 +32,11 @@ body {
 }
 
 .page-section > ul {
-  @apply pl-8 text-base text-slate-800 leading-7;
+  @apply pl-8 text-base text-slate-800 leading-7 mb-8;
 }
 
 .page-section > ul > li {
-  @apply mb-4;
+  @apply mb-4 last:mb-0;
 }
 
 .jump-list a {

docs/components/CalloutInfo.vue

@@ -1,5 +1,5 @@
 <template>
-  <aside class="bg-sky-200 p-4 rounded-lg text-slate-800 leading-8">
+  <aside class="bg-sky-200 p-4 rounded-lg text-slate-800 leading-8 mb-8">
     <svg
       xmlns="http://www.w3.org/2000/svg"
       fill="none"

docs/components/CalloutWarning.vue

@@ -0,0 +1,20 @@
+<template>
+  <aside class="bg-yellow-200 p-4 rounded-lg text-slate-800 leading-8 mb-8">
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke-width="1.5"
+      stroke="currentColor"
+      class="w-6 h-6 inline-block mr-1 relative -top-[0.1em]"
+    >
+      <path
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126ZM12 15.75h.007v.008H12v-.008Z"
+      />
+    </svg>
+
+    <slot />
+  </aside>
+</template>

docs/components/content/Introduction.vue

@@ -11,10 +11,12 @@ import { defineProps } from "vue"
       is built from the ground up to be as small and easy to use as possible.
     </p>
     <p>
-      Under the hood, Tempo mines JavaScript's
-      <code>Intl.DateTimeFormat</code> to extract complex data like timezones
-      offsets and locale aware date formats giving you a simple API to format,
-      parse, and manipulates dates.
+      Tempo is best thought of as a collection of utilities for working with
+      <code>Date</code> objects — an important distinction from other libraries
+      that provide custom date primitives. Under the hood, Tempo mines
+      JavaScript's <code>Intl.DateTimeFormat</code> to extract complex data like
+      timezones offsets and locale aware date formats giving you a simple API to
+      format, parse, and manipulates dates.
     </p>
     <CodeExample file="introduction" />
   </PageSection>

docs/components/content/Modify.vue

@@ -168,7 +168,7 @@ const fns = {
     ],
   },
   removeOffset: {
-    description: `Returns a new Date object with the inverse of the specified timezone offset removed. This can be helpful to normalize time information across timezones.`,
+    description: `Returns a new Date object with the inverse of the specified offset applied. This can be helpful to normalize time information across timezones.`,
     return: "Date",
     arguments: [
       {

docs/components/content/Timezones.vue

@@ -3,6 +3,58 @@
 <template>
   <PageSection id="timezones">
     <HeadingSection title="Timezones" class="text-sky-500" />
-    <p></p>
+    <p>Timezones are challenging for 2 reasons:</p>
+    <ul>
+      <li>1. They are conceptually difficult to understand.</li>
+      <li>2. They involve a lot of geography, history, and politics.</li>
+    </ul>
+    <p>
+      Tempo ships 3 Timezone offset functions that allow you to solve nearly any
+      Timezone problem while maintaining the simplicity of using native
+      <code>Date</code> objects.
+    </p>
+    <HeadingSection title="Key concept" size="sm" class="text-sky-500" />
+    <p>
+      A timezone is really an expression or "view" of a given absolute time. An
+      airplane departing Amsterdam
+      <code>2012-04-07 11:00:00 UTC</code> leaves the ground at the same moment
+      in every timezone on earth. JavaScript’s <code>Date</code> object is
+      "absolute" in the same way as the airplane’s takeoff. A timezone is only a
+      way to express that moment relative the geography and politics of a given
+      region.
+    </p>
+    <HeadingSection title="Using timezones" size="sm" class="text-sky-500" />
+    <h4>Calculating offsets</h4>
+    <p>
+      Tempo uses the <code>Intl.DateTimeFormat</code> API to extract timezone
+      information, that makes working with timezones as simple as possible. The
+      <code>offset()</code> function calculates the amount of offset between any
+      two timezones (given in <code>+-HHmm</code>).
+    </p>
+    <CodeExample file="offset" />
+    <h4>Removing offsets</h4>
+    <p>
+      To display the time of a <code>Date</code> object in a specific timezone
+      you only need to remove the relative offset. Since Tempo operates with
+      native <code>Date</code> objects the resulting <code>Date</code> object is
+      one whose internal methods (like <code>getHours()</code>) will return the
+      time "at" the desired timezone.
+    </p>
+    <CodeExample file="removeOffset" />
+    <CalloutWarning>
+      Tempo utilizes native <code>Date</code> objects. Since these objects only
+      represent an absolute moment in time a date adjusted via the
+      <code>offset</code> function is useful for formatting and display purposes
+      but actually represents a fundamentally different absolute moment in time.
+    </CalloutWarning>
+    <h4>Applying offsets</h4>
+    <p>
+      If you are creating a car rental booking app you want the pickup time to
+      always be relative to the local time of the pickup location. The
+      <code>applyOffset</code> function is used to apply a given offset to a
+      <code>Date</code> object to determine the absolute time in a different
+      timezone.
+    </p>
+    <CodeExample file="applyOffset" />
   </PageSection>
 </template>

docs/examples/applyOffset.ts

@@ -0,0 +1,12 @@
+import { offset, applyOffset } from "@formkit/tempo"
+
+// 💡 Pickup at 9:30 in Europe/Lisbon
+
+// Notice that the time has no offset, thus it is "local":
+const d = "2025-03-25 09:30"
+
+// Lisbon is at UTC+0:
+const lisbonOffset = offset(d, "Europe/Lisbon")
+
+// Apply the offset to the time:
+applyOffset(d, lisbonOffset)

docs/examples/offset.ts

@@ -0,0 +1,18 @@
+import { offset } from "@formkit/tempo"
+
+const date = new Date()
+
+// Your browser’s offset to UTC
+offset(date)
+// Your browser’s offset to Hawaii
+offset(date, "Pacific/Honolulu")
+// Your Hawaii’s offset to UTC
+offset(date, "UTC", "Pacific/Honolulu")
+// The offset from London to New York today
+offset(date, "Europe/London", "America/New_York")
+// The offset from Moscow to Kolkata, India
+offset(date, "Europe/Moscow", "Asia/Kolkata")
+
+// 👀 Dates matter due to DST:
+offset("2023-10-25", "Europe/London", "America/New_York")
+offset("2023-10-30", "Europe/London", "America/New_York")

docs/examples/removeOffset.ts

@@ -0,0 +1,12 @@
+import { format, offset, removeOffset } from "@formkit/tempo"
+
+// rendered at:
+const d = new Date()
+
+// local time:
+format(d, "HH:mm")
+
+const offsetToBerlin = offset(d, "Europe/Berlin")
+const adjusted = removeOffset(d, offsetToBerlin)
+// The time in Berlin
+format(adjusted, "HH:mm")