@classic-homes/theme-svelte 0.1.21 → 0.1.22

package/dist/lib/components/Select.svelte

@@ -2,6 +2,7 @@
   import { Select as SelectPrimitive } from 'bits-ui';
   import { cn } from '../utils.js';
   import { validateNonEmptyArray } from '../validation.js';
+  import Label from './Label.svelte';
 
   export interface SelectOption {
     value: string;
@@ -37,6 +38,8 @@
     id?: string;
     /** Error message to display */
     error?: string;
+    /** Hint text displayed below the select */
+    hint?: string;
   }
 
   let {
@@ -51,8 +54,24 @@
     label,
     id,
     error,
+    hint,
   }: Props = $props();
 
+  // Generate unique IDs for accessibility
+  // Using a random suffix ensures uniqueness if id is not provided
+  const randomSuffix = Math.random().toString(36).substring(2, 9);
+  const componentId = $derived(id || `select-${randomSuffix}`);
+  const hintId = $derived(`${componentId}-hint`);
+  const errorId = $derived(`${componentId}-error`);
+
+  // Compute aria-describedby based on hint and error
+  const describedBy = $derived.by(() => {
+    const ids: string[] = [];
+    if (hint) ids.push(hintId);
+    if (error) ids.push(errorId);
+    return ids.length > 0 ? ids.join(' ') : undefined;
+  });
+
   // Validate props in development
   $effect(() => {
     validateNonEmptyArray(options, 'options', 'Select');
@@ -94,78 +113,112 @@
     value = newValue;
     onValueChange?.(newValue);
   }
+
+  // Determine if we need a container wrapper
+  const hasWrapper = $derived(!!label || !!hint || !!error);
 </script>
 
-{#if label}
-  <span
-    class="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70 mb-1.5 block"
-  >
-    {label}
-    {#if required}
-      <span class="text-destructive">*</span>
+{#if hasWrapper}
+  <div class="space-y-2">
+    {#if label}
+      <Label for={componentId} {disabled}>
+        {label}
+        {#if required}
+          <span class="text-destructive ml-0.5" aria-hidden="true">*</span>
+          <span class="sr-only">(required)</span>
+        {/if}
+      </Label>
     {/if}
-  </span>
-{/if}
 
-<SelectPrimitive.Root
-  type="single"
-  {name}
-  {disabled}
-  {required}
-  {value}
-  items={flatItems}
-  onValueChange={handleValueChange}
->
-  <SelectPrimitive.Trigger
-    {id}
-    class={cn(
-      'flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1',
-      error && 'border-destructive focus:ring-destructive',
-      className
-    )}
-    aria-label={label || placeholder}
-    aria-invalid={error ? 'true' : undefined}
-  >
-    <span class={value ? '' : 'text-muted-foreground'}>
-      {selectedLabel || placeholder}
-    </span>
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      width="24"
-      height="24"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      stroke-width="2"
-      stroke-linecap="round"
-      stroke-linejoin="round"
-      class="h-4 w-4 opacity-50"
+    <SelectPrimitive.Root
+      type="single"
+      {name}
+      {disabled}
+      {required}
+      {value}
+      items={flatItems}
+      onValueChange={handleValueChange}
     >
-      <path d="m6 9 6 6 6-6" />
-    </svg>
-  </SelectPrimitive.Trigger>
-
-  <SelectPrimitive.Content
-    class="isolate relative z-50 min-w-[var(--bits-floating-anchor-width)] overflow-hidden rounded-md border bg-popover text-popover-foreground shadow-md data-[side=bottom]:border-t-0 data-[side=bottom]:rounded-t-none data-[side=top]:border-b-0 data-[side=top]:rounded-b-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2"
-    sideOffset={-1}
-    collisionPadding={8}
-    avoidCollisions={true}
-  >
-    <div class="p-1 max-h-[300px] overflow-y-auto">
-      {#each options as item}
-        {#if isGroup(item)}
-          <SelectPrimitive.Group>
-            <div class="py-1.5 pl-8 pr-2 text-sm font-semibold">
-              {item.label}
-            </div>
-            {#each item.options as option}
+      <SelectPrimitive.Trigger
+        id={componentId}
+        class={cn(
+          'flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1',
+          error && 'border-destructive focus:ring-destructive',
+          className
+        )}
+        aria-label={!label ? placeholder : undefined}
+        aria-invalid={error ? 'true' : undefined}
+        aria-describedby={describedBy}
+      >
+        <span class={value ? '' : 'text-muted-foreground'}>
+          {selectedLabel || placeholder}
+        </span>
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          class="h-4 w-4 opacity-50"
+        >
+          <path d="m6 9 6 6 6-6" />
+        </svg>
+      </SelectPrimitive.Trigger>
+
+      <SelectPrimitive.Content
+        class="isolate relative z-50 min-w-[var(--bits-floating-anchor-width)] overflow-hidden rounded-md border bg-popover text-popover-foreground shadow-md data-[side=bottom]:border-t-0 data-[side=bottom]:rounded-t-none data-[side=top]:border-b-0 data-[side=top]:rounded-b-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2"
+        sideOffset={-1}
+        collisionPadding={8}
+        avoidCollisions={true}
+      >
+        <div class="p-1 max-h-[300px] overflow-y-auto">
+          {#each options as item}
+            {#if isGroup(item)}
+              <SelectPrimitive.Group>
+                <div class="py-1.5 pl-8 pr-2 text-sm font-semibold">
+                  {item.label}
+                </div>
+                {#each item.options as option}
+                  <SelectPrimitive.Item
+                    value={option.value}
+                    label={option.label}
+                    disabled={option.disabled}
+                    class="relative flex w-full cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[disabled]:cursor-default"
+                  >
+                    {#if option.value === value}
+                      <span class="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+                        <svg
+                          xmlns="http://www.w3.org/2000/svg"
+                          width="16"
+                          height="16"
+                          viewBox="0 0 24 24"
+                          fill="none"
+                          stroke="currentColor"
+                          stroke-width="2"
+                          stroke-linecap="round"
+                          stroke-linejoin="round"
+                          class="h-4 w-4"
+                        >
+                          <polyline points="20 6 9 17 4 12" />
+                        </svg>
+                      </span>
+                    {/if}
+                    {option.label}
+                  </SelectPrimitive.Item>
+                {/each}
+              </SelectPrimitive.Group>
+            {:else}
               <SelectPrimitive.Item
-                value={option.value}
-                label={option.label}
-                disabled={option.disabled}
+                value={item.value}
+                label={item.label}
+                disabled={item.disabled}
                 class="relative flex w-full cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[disabled]:cursor-default"
               >
-                {#if option.value === value}
+                {#if item.value === value}
                   <span class="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
                     <svg
                       xmlns="http://www.w3.org/2000/svg"
@@ -183,45 +236,138 @@
                     </svg>
                   </span>
                 {/if}
-                {option.label}
+                {item.label}
               </SelectPrimitive.Item>
-            {/each}
-          </SelectPrimitive.Group>
-        {:else}
-          <SelectPrimitive.Item
-            value={item.value}
-            label={item.label}
-            disabled={item.disabled}
-            class="relative flex w-full cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[disabled]:cursor-default"
-          >
-            {#if item.value === value}
-              <span class="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
-                <svg
-                  xmlns="http://www.w3.org/2000/svg"
-                  width="16"
-                  height="16"
-                  viewBox="0 0 24 24"
-                  fill="none"
-                  stroke="currentColor"
-                  stroke-width="2"
-                  stroke-linecap="round"
-                  stroke-linejoin="round"
-                  class="h-4 w-4"
-                >
-                  <polyline points="20 6 9 17 4 12" />
-                </svg>
-              </span>
             {/if}
-            {item.label}
-          </SelectPrimitive.Item>
-        {/if}
-      {/each}
-    </div>
-  </SelectPrimitive.Content>
-</SelectPrimitive.Root>
-
-{#if error}
-  <p class="text-sm text-destructive mt-1.5" role="alert">
-    {error}
-  </p>
+          {/each}
+        </div>
+      </SelectPrimitive.Content>
+    </SelectPrimitive.Root>
+
+    {#if hint && !error}
+      <p id={hintId} class="text-sm text-muted-foreground">
+        {hint}
+      </p>
+    {/if}
+
+    {#if error}
+      <p id={errorId} class="text-sm text-destructive" role="alert" aria-live="polite">
+        {error}
+      </p>
+    {/if}
+  </div>
+{:else}
+  <SelectPrimitive.Root
+    type="single"
+    {name}
+    {disabled}
+    {required}
+    {value}
+    items={flatItems}
+    onValueChange={handleValueChange}
+  >
+    <SelectPrimitive.Trigger
+      id={componentId}
+      class={cn(
+        'flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1',
+        error && 'border-destructive focus:ring-destructive',
+        className
+      )}
+      aria-label={placeholder}
+      aria-invalid={error ? 'true' : undefined}
+      aria-describedby={describedBy}
+    >
+      <span class={value ? '' : 'text-muted-foreground'}>
+        {selectedLabel || placeholder}
+      </span>
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        class="h-4 w-4 opacity-50"
+      >
+        <path d="m6 9 6 6 6-6" />
+      </svg>
+    </SelectPrimitive.Trigger>
+
+    <SelectPrimitive.Content
+      class="isolate relative z-50 min-w-[var(--bits-floating-anchor-width)] overflow-hidden rounded-md border bg-popover text-popover-foreground shadow-md data-[side=bottom]:border-t-0 data-[side=bottom]:rounded-t-none data-[side=top]:border-b-0 data-[side=top]:rounded-b-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2"
+      sideOffset={-1}
+      collisionPadding={8}
+      avoidCollisions={true}
+    >
+      <div class="p-1 max-h-[300px] overflow-y-auto">
+        {#each options as item}
+          {#if isGroup(item)}
+            <SelectPrimitive.Group>
+              <div class="py-1.5 pl-8 pr-2 text-sm font-semibold">
+                {item.label}
+              </div>
+              {#each item.options as option}
+                <SelectPrimitive.Item
+                  value={option.value}
+                  label={option.label}
+                  disabled={option.disabled}
+                  class="relative flex w-full cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[disabled]:cursor-default"
+                >
+                  {#if option.value === value}
+                    <span class="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+                      <svg
+                        xmlns="http://www.w3.org/2000/svg"
+                        width="16"
+                        height="16"
+                        viewBox="0 0 24 24"
+                        fill="none"
+                        stroke="currentColor"
+                        stroke-width="2"
+                        stroke-linecap="round"
+                        stroke-linejoin="round"
+                        class="h-4 w-4"
+                      >
+                        <polyline points="20 6 9 17 4 12" />
+                      </svg>
+                    </span>
+                  {/if}
+                  {option.label}
+                </SelectPrimitive.Item>
+              {/each}
+            </SelectPrimitive.Group>
+          {:else}
+            <SelectPrimitive.Item
+              value={item.value}
+              label={item.label}
+              disabled={item.disabled}
+              class="relative flex w-full cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[disabled]:cursor-default"
+            >
+              {#if item.value === value}
+                <span class="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+                  <svg
+                    xmlns="http://www.w3.org/2000/svg"
+                    width="16"
+                    height="16"
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    stroke="currentColor"
+                    stroke-width="2"
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                    class="h-4 w-4"
+                  >
+                    <polyline points="20 6 9 17 4 12" />
+                  </svg>
+                </span>
+              {/if}
+              {item.label}
+            </SelectPrimitive.Item>
+          {/if}
+        {/each}
+      </div>
+    </SelectPrimitive.Content>
+  </SelectPrimitive.Root>
 {/if}

package/dist/lib/components/Select.svelte.d.ts

@@ -30,6 +30,8 @@ interface Props {
     id?: string;
     /** Error message to display */
     error?: string;
+    /** Hint text displayed below the select */
+    hint?: string;
 }
 declare const Select: import("svelte").Component<Props, {}, "value">;
 type Select = ReturnType<typeof Select>;

package/dist/lib/components/Slider.svelte

@@ -1,7 +1,9 @@
 <script lang="ts">
   import { Slider as SliderPrimitive } from 'bits-ui';
   import { cn } from '../utils.js';
+  import { generateId, computeDescribedBy } from '../utils/form.js';
   import { tv, type VariantProps } from 'tailwind-variants';
+  import Label from './Label.svelte';
 
   const sliderVariants = tv({
     slots: {
@@ -58,6 +60,10 @@
     showValue?: boolean;
     /** Format function for displayed value */
     formatValue?: (value: number) => string;
+    /** Hint text displayed below the slider */
+    hint?: string;
+    /** Error message to display */
+    error?: string;
     /** Additional class for the container */
     class?: string;
   }
@@ -75,9 +81,20 @@
     label,
     showValue = false,
     formatValue = (v) => String(v),
+    hint,
+    error,
     class: className,
   }: Props = $props();
 
+  // Generate unique IDs for accessibility
+  const randomSuffix = generateId('slider').split('-').pop();
+  const componentId = $derived(`slider-${randomSuffix}`);
+  const hintId = $derived(`${componentId}-hint`);
+  const errorId = $derived(`${componentId}-error`);
+
+  // Compute aria-describedby based on hint and error
+  const describedBy = $derived(computeDescribedBy(hintId, errorId, !!hint, !!error));
+
   const styles = $derived(sliderVariants({ size }));
 
   function handleValueChange(newValue: number[]) {
@@ -100,9 +117,9 @@
   {#if label || showValue}
     <div class="flex items-center justify-between mb-2">
       {#if label}
-        <span class="text-sm font-medium leading-none">
+        <Label for={undefined} {disabled}>
           {label}
-        </span>
+        </Label>
       {/if}
       {#if showValue}
         <span class="text-sm text-muted-foreground tabular-nums">
@@ -123,6 +140,7 @@
     onValueChange={handleValueChange}
     onValueCommit={handleValueCommit}
     class={cn(styles.root(), 'rounded-full bg-secondary')}
+    aria-describedby={describedBy}
   >
     <SliderPrimitive.Range class={styles.range()} />
     {#each value as _, i}
@@ -133,4 +151,16 @@
       />
     {/each}
   </SliderPrimitive.Root>
+
+  {#if hint && !error}
+    <p id={hintId} class="text-sm text-muted-foreground mt-1.5">
+      {hint}
+    </p>
+  {/if}
+
+  {#if error}
+    <p id={errorId} class="text-sm text-destructive mt-1.5" role="alert" aria-live="polite">
+      {error}
+    </p>
+  {/if}
 </div>

package/dist/lib/components/Slider.svelte.d.ts

@@ -23,6 +23,10 @@ declare const Slider: import("svelte").Component<{
     showValue?: boolean;
     /** Format function for displayed value */
     formatValue?: (value: number) => string;
+    /** Hint text displayed below the slider */
+    hint?: string;
+    /** Error message to display */
+    error?: string;
     /** Additional class for the container */
     class?: string;
 }, {}, "value">;

package/dist/lib/composables/useForm.svelte.d.ts

@@ -118,6 +118,12 @@ export interface UseFormReturn<T extends z.ZodObject<z.ZodRawShape>> {
     markDirty: (field: string) => void;
     /** Handle field blur - validates the field and marks dirty */
     handleBlur: (field: keyof z.infer<T>) => void;
+    /** Create a blur handler function for a field (returns a function suitable for event handlers) */
+    createBlurHandler: (field: keyof z.infer<T>) => () => void;
+    /** Get error message for an array field item */
+    getArrayFieldError: (arrayPath: string, index: number, fieldName: string) => string | undefined;
+    /** Build the full path for an array field item (e.g., 'purchasers.0.firstName') */
+    buildArrayFieldPath: (arrayPath: string, index: number, fieldName: string) => string;
 }
 /**
  * Create a form handler with Zod validation and Svelte 5 runes

package/dist/lib/composables/useForm.svelte.js

@@ -205,6 +205,36 @@ export function useForm(options) {
         markDirty(field);
         validateField(field);
     }
+    /**
+     * Create a blur handler function for a field
+     * Returns a function that can be passed directly to event handlers
+     * This is useful when you need to pass a handler without inline function creation
+     */
+    function createBlurHandler(field) {
+        return () => handleBlur(field);
+    }
+    /**
+     * Build the full path for an array field item
+     * @param arrayPath - The base path to the array (e.g., 'purchasers')
+     * @param index - The index within the array
+     * @param fieldName - The field name within the array item (e.g., 'firstName')
+     * @returns The full dot-notation path (e.g., 'purchasers.0.firstName')
+     */
+    function buildArrayFieldPath(arrayPath, index, fieldName) {
+        return `${arrayPath}.${index}.${fieldName}`;
+    }
+    /**
+     * Get error message for an array field item
+     * Convenience method for accessing errors in nested array structures
+     * @param arrayPath - The base path to the array (e.g., 'purchasers')
+     * @param index - The index within the array
+     * @param fieldName - The field name within the array item (e.g., 'firstName')
+     * @returns The error message if present, undefined otherwise
+     */
+    function getArrayFieldError(arrayPath, index, fieldName) {
+        const path = buildArrayFieldPath(arrayPath, index, fieldName);
+        return errors[path];
+    }
     /**
      * Reset form to initial values
      */
@@ -268,5 +298,8 @@ export function useForm(options) {
         setGlobalError,
         markDirty,
         handleBlur,
+        createBlurHandler,
+        getArrayFieldError,
+        buildArrayFieldPath,
     };
 }

package/dist/lib/composables/usePersistedForm.svelte.js

@@ -251,6 +251,9 @@ export function usePersistedForm(options) {
         setGlobalError: baseForm.setGlobalError,
         markDirty: baseForm.markDirty,
         handleBlur: baseForm.handleBlur,
+        createBlurHandler: baseForm.createBlurHandler,
+        getArrayFieldError: baseForm.getArrayFieldError,
+        buildArrayFieldPath: baseForm.buildArrayFieldPath,
         // Override reset to also clear draft
         reset,
         // Persistence-specific methods

package/dist/lib/index.d.ts

@@ -71,6 +71,8 @@ export { toastStore, type Toast as ToastType, type ToastInput } from './stores/t
 export { sidebarStore } from './stores/sidebar.svelte.js';
 export { themeStore, type ThemeMode } from './stores/theme.svelte.js';
 export { cn } from './utils.js';
+export { parseDate, toISOString, formatDate, formatDateTime, isSameDay } from './utils/date.js';
+export { generateId, computeDescribedBy } from './utils/form.js';
 export { tv, type VariantProps } from 'tailwind-variants';
 export { validateNonEmptyArray, validateRequired, validateOneOf, validateRange, validateProps, createValidator, type ValidationResult, } from './validation.js';
 export { perfStart, perfEnd, measure, measureAsync, getPerformanceEntries, clearPerformanceEntries, createPerfMonitor, type PerformanceMark, } from './performance.js';

package/dist/lib/index.js

@@ -93,6 +93,10 @@ export { sidebarStore } from './stores/sidebar.svelte.js';
 export { themeStore } from './stores/theme.svelte.js';
 // Utilities
 export { cn } from './utils.js';
+// Date utilities
+export { parseDate, toISOString, formatDate, formatDateTime, isSameDay } from './utils/date.js';
+// Form utilities
+export { generateId, computeDescribedBy } from './utils/form.js';
 // Re-export tailwind-variants types for consumer convenience
 export { tv } from 'tailwind-variants';
 // Validation utilities (dev-only, tree-shaken in production)

package/dist/lib/utils/date.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Date utility functions for form handling
+ *
+ * These utilities help with converting between Date objects and string formats,
+ * particularly useful for form data binding where backend APIs expect ISO strings.
+ */
+/**
+ * Parse a date from various input formats into a Date object.
+ *
+ * @param input - A Date object, ISO string, or null/undefined
+ * @returns A Date object or null if input is invalid/empty
+ *
+ * @example
+ * parseDate('2024-03-15T10:30:00.000Z') // Date object
+ * parseDate(new Date()) // Same Date object
+ * parseDate(null) // null
+ * parseDate('invalid') // null
+ */
+export declare function parseDate(input: Date | string | null | undefined): Date | null;
+/**
+ * Convert a Date object to an ISO string.
+ *
+ * @param date - A Date object or null
+ * @returns ISO string representation or null if date is invalid/empty
+ *
+ * @example
+ * toISOString(new Date('2024-03-15T10:30:00.000Z')) // '2024-03-15T10:30:00.000Z'
+ * toISOString(null) // null
+ */
+export declare function toISOString(date: Date | null | undefined): string | null;
+/**
+ * Format a Date object to YYYY-MM-DD string format.
+ *
+ * @param date - A Date object or null
+ * @returns Date string in YYYY-MM-DD format or empty string if date is invalid/empty
+ *
+ * @example
+ * formatDate(new Date('2024-03-15T10:30:00.000Z')) // '2024-03-15'
+ * formatDate(null) // ''
+ */
+export declare function formatDate(date: Date | null | undefined): string;
+/**
+ * Format a Date object to YYYY-MM-DDTHH:MM string format (datetime-local input format).
+ *
+ * @param date - A Date object or null
+ * @returns Date string in datetime-local format or empty string if date is invalid/empty
+ *
+ * @example
+ * formatDateTime(new Date('2024-03-15T10:30:00.000Z')) // '2024-03-15T10:30'
+ * formatDateTime(null) // ''
+ */
+export declare function formatDateTime(date: Date | null | undefined): string;
+/**
+ * Check if two dates are the same day (ignoring time).
+ *
+ * @param date1 - First date to compare
+ * @param date2 - Second date to compare
+ * @returns true if both dates are the same day
+ *
+ * @example
+ * isSameDay(new Date('2024-03-15T10:00:00'), new Date('2024-03-15T22:00:00')) // true
+ * isSameDay(new Date('2024-03-15'), new Date('2024-03-16')) // false
+ */
+export declare function isSameDay(date1: Date | null | undefined, date2: Date | null | undefined): boolean;