refactor(useDate): address inspection findings

- Enhance SSR/hydration docs with warning callout and code examples
- Add type-level tests verifying overload safety
- Replace getCurrentInstance() with instanceExists() utility
- Minor import ordering cleanup

Author: johnleider

apps/docs/src/pages/composables/plugins/use-date.md

@@ -368,15 +368,40 @@ app.use(createDatePlugin({
 
 - **parse() format parameter**: The `parse()` method's format parameter is currently ignored. The Temporal API doesn't provide built-in format parsing. The method delegates to `date()` which handles ISO 8601 strings. For custom format parsing, use a library like date-fns or luxon with a custom adapter.
 
-- **SSR Behavior**: When `adapter.date()` is called without arguments:
-  - Browser: Returns current time via `Temporal.Now.plainDateTimeISO()`
-  - Server: Returns epoch (1970-01-01T00:00:00) for deterministic rendering
+### SSR and Hydration
 
-  This is intentional to prevent hydration mismatches. For SSR apps needing current time, pass `Date.now()` explicitly and handle hydration via `<ClientOnly>` (Nuxt) or `v-if` + `onMounted` pattern.
+> [!WARNING]
+> Date formatting can cause hydration mismatches in SSR applications. Server and client environments may produce different formatted output due to timezone differences.
 
-- **Timezone-dependent formatting**: `Intl.DateTimeFormat` uses the system timezone. Server environments (often UTC) and client browsers (user's local timezone) may produce different formatted strings, causing hydration mismatches.
+**SSR Behavior for `adapter.date()`:**
+- Browser: Returns current time via `Temporal.Now.plainDateTimeISO()`
+- Server: Returns epoch (1970-01-01T00:00:00) for deterministic rendering
 
-  **Solutions:**
-  - Set `TZ=UTC` environment variable on your server to match a consistent baseline
-  - Wrap formatted date output in `<ClientOnly>` (Nuxt) or render only after `onMounted`
-  - For critical date displays, serialize dates as ISO strings and format client-side only
+This is intentional to prevent hydration mismatches. For SSR apps needing current time, pass `Date.now()` explicitly.
+
+**Timezone-dependent formatting:** `Intl.DateTimeFormat` uses the system timezone. Server environments (often UTC) and client browsers (user's local timezone) produce different formatted strings.
+
+**Solutions:**
+1. **Nuxt/SSR:** Wrap formatted dates in `<ClientOnly>`:
+   ```vue
+   <ClientOnly>
+     <span>{{ adapter.format(date, 'fullDate') }}</span>
+   </ClientOnly>
+   ```
+
+2. **Vue SSR:** Defer formatting until after hydration:
+   ```vue
+   <script setup lang="ts">
+     const { adapter } = useDate()
+     const isMounted = ref(false)
+     const date = adapter.date('2024-06-15T10:30:00')
+
+     onMounted(() => { isMounted.value = true })
+
+     const formatted = computed(() =>
+       isMounted.value ? adapter.format(date, 'fullDate') : date?.toString()
+     )
+   </script>
+   ```
+
+3. **Server timezone:** Set `TZ=UTC` environment variable on your server for consistent baseline

packages/0/src/composables/useDate/adapters/v0.ts

@@ -13,11 +13,10 @@
  * @see https://github.com/dmtrKovalenko/date-io
  */
 
-// Polyfill
-import { Temporal } from '@js-temporal/polyfill'
-
 // Constants
 import { IN_BROWSER } from '#v0/constants/globals'
+// Polyfill
+import { Temporal } from '@js-temporal/polyfill'
 
 // Utilities
 import { isNull, isNullOrUndefined, isNumber, isString } from '#v0/utilities'

packages/0/src/composables/useDate/index.bench.ts

@@ -1,5 +1,7 @@
 import { Temporal } from '@js-temporal/polyfill'
 import { bench, describe } from 'vitest'
+
+// Adapters
 import { Vuetify0DateAdapter } from './adapters/v0'
 
 describe('useDate benchmarks', () => {

packages/0/src/composables/useDate/index.ssr.test.ts

@@ -11,8 +11,10 @@ vi.mock('#v0/constants/globals', () => ({
   IN_BROWSER: false,
 }))
 
+// Adapters
 // Import after mock is set up
 import { Vuetify0DateAdapter } from './adapters/v0'
+
 import { useDate, createDateFallback } from './index'
 
 describe('useDate SSR', () => {
@@ -56,7 +58,7 @@ describe('useDate SSR', () => {
     })
   })
 
-  describe('Vuetify0DateAdapter in SSR mode', () => {
+  describe('vuetify0DateAdapter in SSR mode', () => {
     it('should return epoch when date() called without arguments', () => {
       const adapter = new Vuetify0DateAdapter('en-US')
       const date = adapter.date()

packages/0/src/composables/useDate/index.test.ts

@@ -1,11 +1,16 @@
-import { describe, it, expect, beforeEach, expectTypeOf } from 'vitest'
 import { Temporal } from '@js-temporal/polyfill'
-import { createDate, createDateContext, createDateFallback, createDatePlugin, useDate } from './index'
+import { describe, it, expect, beforeEach, expectTypeOf } from 'vitest'
+
+// Adapters
 import { Vuetify0DateAdapter } from './adapters/v0'
+
+// Types
 import type { DateAdapter, DateContext } from './index'
 
+import { createDate, createDateContext, createDateFallback, createDatePlugin, useDate } from './index'
+
 describe('useDate', () => {
-  describe('Vuetify0DateAdapter', () => {
+  describe('vuetify0DateAdapter', () => {
     let adapter: Vuetify0DateAdapter
 
     beforeEach(() => {
@@ -822,7 +827,7 @@ describe('useDate', () => {
       })
     })
 
-    describe('SSR behavior', () => {
+    describe('sSR behavior', () => {
       it('should return deterministic date for explicit null/undefined input', () => {
         // When calling date() without arguments in SSR, the implementation
         // returns epoch (1970-01-01) for deterministic rendering.
@@ -1479,6 +1484,9 @@ describe('useDate', () => {
       // useDate returns default type
       const usedCtx = useDate()
       expectTypeOf(usedCtx.adapter.date()).toEqualTypeOf<Temporal.PlainDateTime | null>()
+
+      // Runtime assertion to satisfy vitest/expect-expect rule
+      expect(defaultCtx.adapter).toBeDefined()
     })
 
     // Type-level tests: these verify TypeScript rejects invalid calls
@@ -1492,6 +1500,12 @@ describe('useDate', () => {
 
       // @ts-expect-error - T provided without adapter should fail
       createDatePlugin<Date>()
+
+      // @ts-expect-error - useDate<T>() without namespace should fail (second overload requires string)
+      useDate<Date>()
+
+      // Runtime assertion to satisfy vitest/expect-expect rule
+      expect(true).toBe(true)
     })
   })
 })

packages/0/src/composables/useDate/index.ts

@@ -37,10 +37,11 @@
  * ```
  */
 
+// Foundational
+import { createContext, useContext } from '#v0/composables/createContext'
 // Factories
 import { createPlugin } from '#v0/composables/createPlugin'
 import { createTrinity } from '#v0/composables/createTrinity'
-import { createContext, useContext } from '#v0/composables/createContext'
 
 // Composables
 import { useLocale } from '#v0/composables/useLocale'
@@ -49,14 +50,14 @@ import { useLocale } from '#v0/composables/useLocale'
 import { Vuetify0DateAdapter } from '#v0/composables/useDate/adapters'
 
 // Utilities
-import { getCurrentInstance, computed, watchEffect, onScopeDispose } from 'vue'
-import { isNullOrUndefined } from '#v0/utilities'
+import { instanceExists, isNullOrUndefined } from '#v0/utilities'
+import { computed, watchEffect, onScopeDispose } from 'vue'
 
 // Types
-import type { DateAdapter } from '#v0/composables/useDate/adapters'
-import type { App, ComputedRef } from 'vue'
 import type { ContextTrinity } from '#v0/composables/createTrinity'
+import type { DateAdapter } from '#v0/composables/useDate/adapters'
 import type { Temporal } from '@js-temporal/polyfill'
+import type { App, ComputedRef } from 'vue'
 
 // Exports
 export type { DateAdapter } from '#v0/composables/useDate/adapters'
@@ -178,7 +179,7 @@ function createDateInternal<T> (
   let localeContext: ReturnType<typeof useLocale> | null = null
 
   try {
-    if (getCurrentInstance()) {
+    if (instanceExists()) {
       localeContext = useLocale()
     }
   } catch {
@@ -193,7 +194,7 @@ function createDateInternal<T> (
   ))
 
   // Keep adapter locale in sync (only when in component scope)
-  if (getCurrentInstance()) {
+  if (instanceExists()) {
     const stop = watchEffect(() => {
       const loc = locale.value
 
@@ -448,7 +449,7 @@ export function useDate<T = DefaultDateType> (namespace = 'v0:date'): DateContex
   // Safe cast: fallback only used when T = DefaultDateType (first overload) or context missing
   const fallback = createDateFallback() as unknown as DateContext<T>
 
-  if (!getCurrentInstance()) return fallback
+  if (!instanceExists()) return fallback
 
   try {
     return useContext<DateContext<T>>(namespace, fallback)