@jmruthers/pace-core 0.5.185 → 0.5.187

package/dist/components.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/components/DateTimeField/DateTimeField.tsx","../src/components/DatePickerWithTimezone/DatePickerWithTimezone.tsx"],"sourcesContent":["/**\n * @file DateTimeField Component\n * @package @jmruthers/pace-core\n * @module Components/DateTimeField\n * @since 0.1.0\n *\n * Form input component for datetime values with timezone support.\n * Handles UTC ↔ timezone conversion automatically.\n *\n * Features:\n * - Automatic UTC ↔ timezone conversion\n * - Prevents unwanted conversions during user editing\n * - Shows timezone information when not UTC\n * - Supports both ISO string and Date object values\n * - Uses native datetime-local input type\n * - Accessible form field with proper labels\n *\n * @example\n * ```tsx\n * import { DateTimeField } from '@jmruthers/pace-core/components';\n * import { useState } from 'react';\n *\n * function EventForm() {\n *   const [startTime, setStartTime] = useState<string>();\n *\n *   return (\n *     <DateTimeField\n *       label=\"Start Time\"\n *       value={startTime}\n *       onChange={setStartTime}\n *       timezone=\"America/New_York\"\n *       required\n *     />\n *   );\n * }\n * ```\n *\n * @accessibility\n * - Proper label association with htmlFor\n * - Required field indicators\n * - Screen reader friendly\n * - Keyboard navigation support\n * - Focus management\n */\n\nimport * as React from 'react';\nimport { format, parse } from 'date-fns';\nimport { Label } from '../Label';\nimport { Input } from '../Input';\nimport { cn } from '../../utils/core/cn';\nimport { toZonedTime, fromZonedTime, getUserTimeZone } from '../../utils/timezone';\n\n/**\n * Props for the DateTimeField component\n */\nexport interface DateTimeFieldProps {\n  /**\n   * Field label\n   */\n  label: string;\n  /**\n   * UTC date value (ISO string, Date object, or undefined)\n   */\n  value: string | Date | undefined;\n  /**\n   * Change handler that receives UTC value (ISO string or Date object)\n   */\n  onChange: (value: string | Date | undefined) => void;\n  /**\n   * Target timezone for display (default: 'UTC')\n   */\n  timezone?: string;\n  /**\n   * Whether the field is required\n   */\n  required?: boolean;\n  /**\n   * Additional CSS classes\n   */\n  className?: string;\n  /**\n   * If true, onChange returns Date object instead of ISO string\n   */\n  returnAsDate?: boolean;\n  /**\n   * Input id (auto-generated if not provided)\n   */\n  id?: string;\n  /**\n   * Helper text to display below the label\n   */\n  helperText?: string;\n  /**\n   * Error message to display\n   */\n  error?: string;\n}\n\n/**\n * DateTimeField component\n * Form input for datetime values with automatic timezone conversion\n *\n * @param props - DateTimeField configuration\n * @returns JSX.Element - The rendered datetime field\n */\nexport function DateTimeField({\n  label,\n  value,\n  onChange,\n  timezone = 'UTC',\n  required = false,\n  className,\n  returnAsDate = false,\n  id,\n  helperText,\n  error\n}: DateTimeFieldProps) {\n  const [isEditing, setIsEditing] = React.useState(false);\n  const inputRef = React.useRef<HTMLInputElement>(null);\n  const fieldId = id || `datetime-field-${React.useId()}`;\n\n  // Convert UTC value to timezone for display\n  const getDisplayValue = React.useCallback((): string => {\n    if (!value) {\n      return '';\n    }\n\n    try {\n      let dateObj: Date;\n      if (typeof value === 'string') {\n        dateObj = new Date(value);\n      } else {\n        dateObj = value;\n      }\n\n      if (!dateObj || isNaN(dateObj.getTime())) {\n        return '';\n      }\n\n      // Convert UTC to timezone\n      const zonedDate = toZonedTime(dateObj, timezone);\n\n      // Format for datetime-local input (YYYY-MM-DDTHH:mm)\n      return format(zonedDate, \"yyyy-MM-dd'T'HH:mm\");\n    } catch {\n      return '';\n    }\n  }, [value, timezone]);\n\n  const displayValue = isEditing ? undefined : getDisplayValue();\n\n  // Handle input change\n  const handleChange = React.useCallback((e: React.ChangeEvent<HTMLInputElement>) => {\n    setIsEditing(true);\n    const inputValue = e.target.value;\n\n    if (!inputValue) {\n      onChange(undefined);\n      return;\n    }\n\n    try {\n      // Parse the datetime-local value (in timezone)\n      const localDate = parse(inputValue, \"yyyy-MM-dd'T'HH:mm\", new Date());\n\n      if (isNaN(localDate.getTime())) {\n        onChange(undefined);\n        return;\n      }\n\n      // Convert from timezone to UTC\n      const utcDate = fromZonedTime(localDate, timezone);\n\n      // Return as ISO string or Date object\n      if (returnAsDate) {\n        onChange(utcDate);\n      } else {\n        onChange(utcDate.toISOString());\n      }\n    } catch {\n      onChange(undefined);\n    }\n  }, [timezone, returnAsDate, onChange]);\n\n  // Handle blur to stop editing mode\n  const handleBlur = React.useCallback(() => {\n    setIsEditing(false);\n  }, []);\n\n  // Get timezone display text\n  const getTimezoneDisplay = React.useCallback((): string => {\n    if (timezone === 'UTC') {\n      return '';\n    }\n\n    const userTz = getUserTimeZone();\n    if (timezone === userTz) {\n      return 'Local';\n    }\n\n    return timezone;\n  }, [timezone]);\n\n  const timezoneDisplay = getTimezoneDisplay();\n\n  return (\n    <div className={cn('space-y-2', className)}>\n      <Label htmlFor={fieldId} required={required} helperText={helperText} error={error}>\n        {label}\n      </Label>\n      <div className=\"relative\">\n        <Input\n          ref={inputRef}\n          id={fieldId}\n          type=\"datetime-local\"\n          value={displayValue}\n          onChange={handleChange}\n          onBlur={handleBlur}\n          required={required}\n          error={!!error}\n          className=\"w-full\"\n        />\n        {timezoneDisplay && (\n          <span className=\"absolute right-3 top-1/2 -translate-y-1/2 text-sm text-muted-foreground pointer-events-none\">\n            {timezoneDisplay}\n          </span>\n        )}\n      </div>\n    </div>\n  );\n}\n\n","/**\n * @file DatePickerWithTimezone Component\n * @package @jmruthers/pace-core\n * @module Components/DatePickerWithTimezone\n * @since 0.1.0\n *\n * Date picker component that displays timezone information alongside the calendar.\n * Provides a calendar interface with timezone context for date selection.\n *\n * Features:\n * - Calendar date selection\n * - Timezone display (shows \"Local\" when matches user timezone)\n * - Optional \"Done\" button\n * - Accessible date selection\n * - Keyboard navigation support\n *\n * @example\n * ```tsx\n * import { DatePickerWithTimezone } from '@jmruthers/pace-core/components';\n * import { useState } from 'react';\n *\n * function DateSelector() {\n *   const [date, setDate] = useState<Date>();\n *\n *   return (\n *     <DatePickerWithTimezone\n *       selected={date}\n *       onSelect={setDate}\n *       timezone=\"America/New_York\"\n *       onDone={() => console.log('Date selected')}\n *     />\n *   );\n * }\n * ```\n *\n * @accessibility\n * - WCAG 2.1 AA compliant\n * - Keyboard navigation support\n * - Screen reader friendly\n * - Focus management\n * - Proper ARIA attributes\n */\n\nimport * as React from 'react';\nimport { Calendar } from '../Calendar';\nimport { Button } from '../Button';\nimport { Clock } from 'lucide-react';\nimport { getUserTimeZone } from '../../utils/timezone';\nimport { cn } from '../../utils/core/cn';\n\n/**\n * Props for the DatePickerWithTimezone component\n */\nexport interface DatePickerWithTimezoneProps {\n  /**\n   * Currently selected date\n   */\n  selected?: Date;\n  /**\n   * Date selection handler\n   */\n  onSelect: (date: Date | undefined) => void;\n  /**\n   * Optional callback when \"Done\" button is clicked\n   */\n  onDone?: () => void;\n  /**\n   * Timezone to display (defaults to user's timezone)\n   */\n  timezone?: string;\n  /**\n   * Additional CSS classes\n   */\n  className?: string;\n}\n\n/**\n * DatePickerWithTimezone component\n * Date picker with timezone information display\n *\n * @param props - DatePickerWithTimezone configuration\n * @returns JSX.Element - The rendered date picker with timezone\n */\nexport function DatePickerWithTimezone({\n  selected,\n  onSelect,\n  onDone,\n  timezone,\n  className\n}: DatePickerWithTimezoneProps) {\n  const userTimezone = getUserTimeZone();\n  const displayTimezone = timezone || userTimezone;\n  const timezoneDisplay = displayTimezone === userTimezone ? 'Local' : displayTimezone;\n\n  return (\n    <div className={cn('flex flex-col', className)}>\n      <div className=\"p-3\">\n        <Calendar\n          mode=\"single\"\n          selected={selected}\n          onSelect={onSelect}\n          initialFocus\n          captionLayout=\"dropdown-buttons\"\n          fromYear={1900}\n          toYear={2100}\n          className=\"p-0\"\n        />\n      </div>\n\n      <div className=\"flex items-center justify-between border-t border-border px-3 py-2\">\n        <div className=\"flex items-center gap-2 text-sm text-muted-foreground\">\n          <Clock className=\"h-4 w-4\" aria-hidden=\"true\" />\n          <span>\n            Timezone: <span aria-label={`Timezone ${timezoneDisplay}`}>{timezoneDisplay}</span>\n          </span>\n        </div>\n        {onDone && (\n          <Button onClick={onDone} size=\"sm\" className=\"h-8\">\n            Done\n          </Button>\n        )}\n      </div>\n    </div>\n  );\n}\n\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,YAAY,WAAW;AACvB,SAAS,QAAQ,aAAa;AAiKxB,cAGA,YAHA;AAtGC,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA,WAAW;AAAA,EACX,WAAW;AAAA,EACX;AAAA,EACA,eAAe;AAAA,EACf;AAAA,EACA;AAAA,EACA;AACF,GAAuB;AACrB,QAAM,CAAC,WAAW,YAAY,IAAU,eAAS,KAAK;AACtD,QAAM,WAAiB,aAAyB,IAAI;AACpD,QAAM,UAAU,MAAM,kBAAwB,YAAM,CAAC;AAGrD,QAAM,kBAAwB,kBAAY,MAAc;AACtD,QAAI,CAAC,OAAO;AACV,aAAO;AAAA,IACT;AAEA,QAAI;AACF,UAAI;AACJ,UAAI,OAAO,UAAU,UAAU;AAC7B,kBAAU,IAAI,KAAK,KAAK;AAAA,MAC1B,OAAO;AACL,kBAAU;AAAA,MACZ;AAEA,UAAI,CAAC,WAAW,MAAM,QAAQ,QAAQ,CAAC,GAAG;AACxC,eAAO;AAAA,MACT;AAGA,YAAM,YAAY,YAAY,SAAS,QAAQ;AAG/C,aAAO,OAAO,WAAW,oBAAoB;AAAA,IAC/C,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF,GAAG,CAAC,OAAO,QAAQ,CAAC;AAEpB,QAAM,eAAe,YAAY,SAAY,gBAAgB;AAG7D,QAAM,eAAqB,kBAAY,CAAC,MAA2C;AACjF,iBAAa,IAAI;AACjB,UAAM,aAAa,EAAE,OAAO;AAE5B,QAAI,CAAC,YAAY;AACf,eAAS,MAAS;AAClB;AAAA,IACF;AAEA,QAAI;AAEF,YAAM,YAAY,MAAM,YAAY,sBAAsB,oBAAI,KAAK,CAAC;AAEpE,UAAI,MAAM,UAAU,QAAQ,CAAC,GAAG;AAC9B,iBAAS,MAAS;AAClB;AAAA,MACF;AAGA,YAAM,UAAU,cAAc,WAAW,QAAQ;AAGjD,UAAI,cAAc;AAChB,iBAAS,OAAO;AAAA,MAClB,OAAO;AACL,iBAAS,QAAQ,YAAY,CAAC;AAAA,MAChC;AAAA,IACF,QAAQ;AACN,eAAS,MAAS;AAAA,IACpB;AAAA,EACF,GAAG,CAAC,UAAU,cAAc,QAAQ,CAAC;AAGrC,QAAM,aAAmB,kBAAY,MAAM;AACzC,iBAAa,KAAK;AAAA,EACpB,GAAG,CAAC,CAAC;AAGL,QAAM,qBAA2B,kBAAY,MAAc;AACzD,QAAI,aAAa,OAAO;AACtB,aAAO;AAAA,IACT;AAEA,UAAM,SAAS,gBAAgB;AAC/B,QAAI,aAAa,QAAQ;AACvB,aAAO;AAAA,IACT;AAEA,WAAO;AAAA,EACT,GAAG,CAAC,QAAQ,CAAC;AAEb,QAAM,kBAAkB,mBAAmB;AAE3C,SACE,qBAAC,SAAI,WAAW,GAAG,aAAa,SAAS,GACvC;AAAA,wBAAC,SAAM,SAAS,SAAS,UAAoB,YAAwB,OAClE,iBACH;AAAA,IACA,qBAAC,SAAI,WAAU,YACb;AAAA;AAAA,QAAC;AAAA;AAAA,UACC,KAAK;AAAA,UACL,IAAI;AAAA,UACJ,MAAK;AAAA,UACL,OAAO;AAAA,UACP,UAAU;AAAA,UACV,QAAQ;AAAA,UACR;AAAA,UACA,OAAO,CAAC,CAAC;AAAA,UACT,WAAU;AAAA;AAAA,MACZ;AAAA,MACC,mBACC,oBAAC,UAAK,WAAU,+FACb,2BACH;AAAA,OAEJ;AAAA,KACF;AAEJ;;;ACxLA,SAAS,aAAa;AAmDd,gBAAAA,MAeE,QAAAC,aAfF;AAdD,SAAS,uBAAuB;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAAgC;AAC9B,QAAM,eAAe,gBAAgB;AACrC,QAAM,kBAAkB,YAAY;AACpC,QAAM,kBAAkB,oBAAoB,eAAe,UAAU;AAErE,SACE,gBAAAA,MAAC,SAAI,WAAW,GAAG,iBAAiB,SAAS,GAC3C;AAAA,oBAAAD,KAAC,SAAI,WAAU,OACb,0BAAAA;AAAA,MAAC;AAAA;AAAA,QACC,MAAK;AAAA,QACL;AAAA,QACA;AAAA,QACA,cAAY;AAAA,QACZ,eAAc;AAAA,QACd,UAAU;AAAA,QACV,QAAQ;AAAA,QACR,WAAU;AAAA;AAAA,IACZ,GACF;AAAA,IAEA,gBAAAC,MAAC,SAAI,WAAU,sEACb;AAAA,sBAAAA,MAAC,SAAI,WAAU,yDACb;AAAA,wBAAAD,KAAC,SAAM,WAAU,WAAU,eAAY,QAAO;AAAA,QAC9C,gBAAAC,MAAC,UAAK;AAAA;AAAA,UACM,gBAAAD,KAAC,UAAK,cAAY,YAAY,eAAe,IAAK,2BAAgB;AAAA,WAC9E;AAAA,SACF;AAAA,MACC,UACC,gBAAAA,KAAC,UAAO,SAAS,QAAQ,MAAK,MAAK,WAAU,OAAM,kBAEnD;AAAA,OAEJ;AAAA,KACF;AAEJ;","names":["jsx","jsxs"]}
+{"version":3,"sources":["../src/components/DateTimeField/DateTimeField.tsx","../src/components/DatePickerWithTimezone/DatePickerWithTimezone.tsx"],"sourcesContent":["/**\n * @file DateTimeField Component\n * @package @jmruthers/pace-core\n * @module Components/DateTimeField\n * @since 0.1.0\n *\n * Form input component for datetime values with timezone support.\n * Handles UTC ↔ timezone conversion automatically.\n *\n * Features:\n * - Automatic UTC ↔ timezone conversion\n * - Prevents unwanted conversions during user editing\n * - Shows timezone information when not UTC\n * - Supports both ISO string and Date object values\n * - Uses native datetime-local input type\n * - Accessible form field with proper labels\n *\n * @example\n * ```tsx\n * import { DateTimeField } from '@jmruthers/pace-core/components';\n * import { useState } from 'react';\n *\n * function EventForm() {\n *   const [startTime, setStartTime] = useState<string>();\n *\n *   return (\n *     <DateTimeField\n *       label=\"Start Time\"\n *       value={startTime}\n *       onChange={setStartTime}\n *       timezone=\"America/New_York\"\n *       required\n *     />\n *   );\n * }\n * ```\n *\n * @accessibility\n * - Proper label association with htmlFor\n * - Required field indicators\n * - Screen reader friendly\n * - Keyboard navigation support\n * - Focus management\n */\n\nimport * as React from 'react';\nimport { format, parse } from 'date-fns';\nimport { Label } from '../Label';\nimport { Input } from '../Input';\nimport { cn } from '../../utils/core/cn';\nimport { toZonedTime, fromZonedTime, getUserTimeZone } from '../../utils/timezone';\n\n/**\n * Props for the DateTimeField component\n */\nexport interface DateTimeFieldProps {\n  /**\n   * Field label\n   */\n  label: string;\n  /**\n   * UTC date value (ISO string, Date object, or undefined)\n   */\n  value: string | Date | undefined;\n  /**\n   * Change handler that receives UTC value (ISO string or Date object)\n   */\n  onChange: (value: string | Date | undefined) => void;\n  /**\n   * Target timezone for display (default: 'UTC')\n   */\n  timezone?: string;\n  /**\n   * Whether the field is required\n   */\n  required?: boolean;\n  /**\n   * Additional CSS classes\n   */\n  className?: string;\n  /**\n   * If true, onChange returns Date object instead of ISO string\n   */\n  returnAsDate?: boolean;\n  /**\n   * Input id (auto-generated if not provided)\n   */\n  id?: string;\n  /**\n   * Helper text to display below the label\n   */\n  helperText?: string;\n  /**\n   * Error message to display\n   */\n  error?: string;\n}\n\n/**\n * DateTimeField component\n * Form input for datetime values with automatic timezone conversion\n *\n * @param props - DateTimeField configuration\n * @returns JSX.Element - The rendered datetime field\n */\nexport function DateTimeField({\n  label,\n  value,\n  onChange,\n  timezone = 'UTC',\n  required = false,\n  className,\n  returnAsDate = false,\n  id,\n  helperText,\n  error\n}: DateTimeFieldProps) {\n  const [isEditing, setIsEditing] = React.useState(false);\n  const inputRef = React.useRef<HTMLInputElement>(null);\n  const fieldId = id || `datetime-field-${React.useId()}`;\n\n  // Convert UTC value to timezone for display\n  const getDisplayValue = React.useCallback((): string => {\n    if (!value) {\n      return '';\n    }\n\n    try {\n      let dateObj: Date;\n      if (typeof value === 'string') {\n        dateObj = new Date(value);\n      } else {\n        dateObj = value;\n      }\n\n      if (!dateObj || isNaN(dateObj.getTime())) {\n        return '';\n      }\n\n      // Convert UTC to timezone\n      const zonedDate = toZonedTime(dateObj, timezone);\n\n      // Format for datetime-local input (YYYY-MM-DDTHH:mm)\n      return format(zonedDate, \"yyyy-MM-dd'T'HH:mm\");\n    } catch {\n      return '';\n    }\n  }, [value, timezone]);\n\n  const displayValue = isEditing ? undefined : getDisplayValue();\n\n  // Handle input change\n  const handleChange = React.useCallback((e: React.ChangeEvent<HTMLInputElement>) => {\n    setIsEditing(true);\n    const inputValue = e.target.value;\n\n    if (!inputValue) {\n      onChange(undefined);\n      return;\n    }\n\n    try {\n      // Parse the datetime-local value (in timezone)\n      const localDate = parse(inputValue, \"yyyy-MM-dd'T'HH:mm\", new Date());\n\n      if (isNaN(localDate.getTime())) {\n        onChange(undefined);\n        return;\n      }\n\n      // Convert from timezone to UTC\n      const utcDate = fromZonedTime(localDate, timezone);\n\n      // Return as ISO string or Date object\n      if (returnAsDate) {\n        onChange(utcDate);\n      } else {\n        onChange(utcDate.toISOString());\n      }\n    } catch {\n      onChange(undefined);\n    }\n  }, [timezone, returnAsDate, onChange]);\n\n  // Handle blur to stop editing mode\n  const handleBlur = React.useCallback(() => {\n    setIsEditing(false);\n  }, []);\n\n  // Get timezone display text\n  const getTimezoneDisplay = React.useCallback((): string => {\n    if (timezone === 'UTC') {\n      return '';\n    }\n\n    const userTz = getUserTimeZone();\n    if (timezone === userTz) {\n      return 'Local';\n    }\n\n    return timezone;\n  }, [timezone]);\n\n  const timezoneDisplay = getTimezoneDisplay();\n\n  return (\n    <div className={cn('space-y-2', className)}>\n      <Label htmlFor={fieldId} required={required} helperText={helperText} error={error}>\n        {label}\n      </Label>\n      <div className=\"relative\">\n        <Input\n          ref={inputRef}\n          id={fieldId}\n          type=\"datetime-local\"\n          value={displayValue}\n          onChange={handleChange}\n          onBlur={handleBlur}\n          required={required}\n          error={!!error}\n          className=\"w-full\"\n        />\n        {timezoneDisplay && (\n          <span className=\"absolute right-3 top-1/2 -translate-y-1/2 text-sm text-muted-foreground pointer-events-none\">\n            {timezoneDisplay}\n          </span>\n        )}\n      </div>\n    </div>\n  );\n}\n\n","/**\n * @file DatePickerWithTimezone Component\n * @package @jmruthers/pace-core\n * @module Components/DatePickerWithTimezone\n * @since 0.1.0\n *\n * Date picker component that displays timezone information alongside the calendar.\n * Provides a calendar interface with timezone context for date selection.\n *\n * Features:\n * - Calendar date selection\n * - Timezone display (shows \"Local\" when matches user timezone)\n * - Optional \"Done\" button\n * - Accessible date selection\n * - Keyboard navigation support\n *\n * @example\n * ```tsx\n * import { DatePickerWithTimezone } from '@jmruthers/pace-core/components';\n * import { useState } from 'react';\n *\n * function DateSelector() {\n *   const [date, setDate] = useState<Date>();\n *\n *   return (\n *     <DatePickerWithTimezone\n *       selected={date}\n *       onSelect={setDate}\n *       timezone=\"America/New_York\"\n *       onDone={() => console.log('Date selected')}\n *     />\n *   );\n * }\n * ```\n *\n * @accessibility\n * - WCAG 2.1 AA compliant\n * - Keyboard navigation support\n * - Screen reader friendly\n * - Focus management\n * - Proper ARIA attributes\n */\n\nimport * as React from 'react';\nimport { Calendar } from '../Calendar';\nimport { Button } from '../Button';\nimport { Clock } from 'lucide-react';\nimport { getUserTimeZone } from '../../utils/timezone';\nimport { cn } from '../../utils/core/cn';\n\n/**\n * Props for the DatePickerWithTimezone component\n */\nexport interface DatePickerWithTimezoneProps {\n  /**\n   * Currently selected date\n   */\n  selected?: Date;\n  /**\n   * Date selection handler\n   */\n  onSelect: (date: Date | undefined) => void;\n  /**\n   * Optional callback when \"Done\" button is clicked\n   */\n  onDone?: () => void;\n  /**\n   * Timezone to display (defaults to user's timezone)\n   */\n  timezone?: string;\n  /**\n   * Additional CSS classes\n   */\n  className?: string;\n}\n\n/**\n * DatePickerWithTimezone component\n * Date picker with timezone information display\n *\n * @param props - DatePickerWithTimezone configuration\n * @returns JSX.Element - The rendered date picker with timezone\n */\nexport function DatePickerWithTimezone({\n  selected,\n  onSelect,\n  onDone,\n  timezone,\n  className\n}: DatePickerWithTimezoneProps) {\n  const userTimezone = getUserTimeZone();\n  const displayTimezone = timezone || userTimezone;\n  const timezoneDisplay = displayTimezone === userTimezone ? 'Local' : displayTimezone;\n\n  return (\n    <div className={cn('flex flex-col', className)}>\n      <div className=\"p-3\">\n        <Calendar\n          mode=\"single\"\n          selected={selected}\n          onSelect={onSelect}\n          initialFocus\n          captionLayout=\"dropdown-buttons\"\n          fromYear={1900}\n          toYear={2100}\n          className=\"p-0\"\n        />\n      </div>\n\n      <div className=\"flex items-center justify-between border-t border-border px-3 py-2\">\n        <div className=\"flex items-center gap-2 text-sm text-muted-foreground\">\n          <Clock className=\"h-4 w-4\" aria-hidden=\"true\" />\n          <span>\n            Timezone: <span aria-label={`Timezone ${timezoneDisplay}`}>{timezoneDisplay}</span>\n          </span>\n        </div>\n        {onDone && (\n          <Button onClick={onDone} size=\"sm\" className=\"h-8\">\n            Done\n          </Button>\n        )}\n      </div>\n    </div>\n  );\n}\n\n"],"mappings":"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","names":["jsx","jsxs"]}

package/dist/{database.generated-CBmg2950.d.ts → database.generated-DI89OQeI.d.ts}

@@ -3307,13 +3307,13 @@ type Database = {
                     }
                 ];
             };
-            pace_id_documents: {
+            pace_identification: {
                 Row: {
                     created_at: string | null;
                     document_number: string | null;
-                    document_type: string;
                     expiry_date: string | null;
                     id: string;
+                    identification_type_id: number | null;
                     issue_city: string | null;
                     issue_country: string | null;
                     issue_date: string | null;
@@ -3326,9 +3326,9 @@ type Database = {
                 Insert: {
                     created_at?: string | null;
                     document_number?: string | null;
-                    document_type: string;
                     expiry_date?: string | null;
                     id?: string;
+                    identification_type_id?: number | null;
                     issue_city?: string | null;
                     issue_country?: string | null;
                     issue_date?: string | null;
@@ -3341,9 +3341,9 @@ type Database = {
                 Update: {
                     created_at?: string | null;
                     document_number?: string | null;
-                    document_type?: string;
                     expiry_date?: string | null;
                     id?: string;
+                    identification_type_id?: number | null;
                     issue_city?: string | null;
                     issue_country?: string | null;
                     issue_date?: string | null;
@@ -3355,14 +3355,21 @@ type Database = {
                 };
                 Relationships: [
                     {
-                        foreignKeyName: "fk_pace_id_documents_organisation_id";
+                        foreignKeyName: "fk_pace_identification_organisation_id";
                         columns: ["organisation_id"];
                         isOneToOne: false;
                         referencedRelation: "organisations";
                         referencedColumns: ["id"];
                     },
                     {
-                        foreignKeyName: "identification_documents_member_id_fkey";
+                        foreignKeyName: "fk_pace_identification_type_id";
+                        columns: ["identification_type_id"];
+                        isOneToOne: false;
+                        referencedRelation: "pace_identification_type";
+                        referencedColumns: ["id"];
+                    },
+                    {
+                        foreignKeyName: "pace_identification_member_id_fkey";
                         columns: ["member_id"];
                         isOneToOne: false;
                         referencedRelation: "pace_member";
@@ -3370,6 +3377,53 @@ type Database = {
                     }
                 ];
             };
+            pace_identification_type: {
+                Row: {
+                    created_at: string | null;
+                    created_by: string | null;
+                    description: string | null;
+                    id: number;
+                    is_active: boolean | null;
+                    name: string;
+                    organisation_id: string;
+                    sort_order: number | null;
+                    updated_at: string | null;
+                    updated_by: string | null;
+                };
+                Insert: {
+                    created_at?: string | null;
+                    created_by?: string | null;
+                    description?: string | null;
+                    id?: never;
+                    is_active?: boolean | null;
+                    name: string;
+                    organisation_id: string;
+                    sort_order?: number | null;
+                    updated_at?: string | null;
+                    updated_by?: string | null;
+                };
+                Update: {
+                    created_at?: string | null;
+                    created_by?: string | null;
+                    description?: string | null;
+                    id?: never;
+                    is_active?: boolean | null;
+                    name?: string;
+                    organisation_id?: string;
+                    sort_order?: number | null;
+                    updated_at?: string | null;
+                    updated_by?: string | null;
+                };
+                Relationships: [
+                    {
+                        foreignKeyName: "pace_identification_type_organisation_id_fkey";
+                        columns: ["organisation_id"];
+                        isOneToOne: false;
+                        referencedRelation: "organisations";
+                        referencedColumns: ["id"];
+                    }
+                ];
+            };
             pace_member: {
                 Row: {
                     address_id: string | null;
@@ -3839,7 +3893,7 @@ type Database = {
                     }
                 ];
             };
-            pace_qualifications: {
+            pace_qualification: {
                 Row: {
                     created_at: string | null;
                     credential_id: string | null;
@@ -3881,14 +3935,14 @@ type Database = {
                 };
                 Relationships: [
                     {
-                        foreignKeyName: "fk_pace_qualifications_organisation_id";
+                        foreignKeyName: "fk_pace_qualification_organisation_id";
                         columns: ["organisation_id"];
                         isOneToOne: false;
                         referencedRelation: "organisations";
                         referencedColumns: ["id"];
                     },
                     {
-                        foreignKeyName: "qualifications_member_id_fkey";
+                        foreignKeyName: "pace_qualification_member_id_fkey";
                         columns: ["member_id"];
                         isOneToOne: false;
                         referencedRelation: "pace_member";

package/dist/{file-reference-BjR39ktt.d.ts → file-reference-D037xOFK.d.ts}

@@ -47,6 +47,7 @@ declare enum FileCategory {
  * Options for uploading a file with a file reference
  * @property pageContext - The page context where the file upload occurs (e.g., 'configuration', 'forms', 'applications')
  *                          Used for context-aware permission checks. Required to check appropriate page-level permissions.
+ * @property event_id - Optional event ID for event-scoped permission checks. Required for event-based apps.
  */
 interface FileUploadOptions {
     table_name: string;
@@ -54,7 +55,9 @@ interface FileUploadOptions {
     organisation_id: string;
     app_id: AppId;
     category: FileCategory;
+    folder: string;
     pageContext: string;
+    event_id?: string;
     is_public?: boolean;
     custom_metadata?: Record<string, unknown>;
 }
@@ -73,7 +76,6 @@ interface FileReferenceService {
 }
 interface StorageUploadOptions {
     orgId: string;
-    category: FileCategory;
     isPublic?: boolean;
     customPath?: string;
 }

package/dist/hooks.d.ts

@@ -1,17 +1,17 @@
 export { u as useToast } from './useToast-C8gR5ir4.js';
-import { S as StorageUploadOptions, a as StorageUploadResult, b as StorageListOptions, c as StorageListResult, d as StorageFileInfo } from './usePublicRouteParams-CvnC3d-e.js';
-export { O as OrganisationSecurityHook, l as UseAppConfigReturn, i as UseFormDialogOptions, j as UseFormDialogReturn, U as UseOrganisationPermissionsReturn, F as UsePublicEventLogoOptions, E as UsePublicEventLogoReturn, B as UsePublicEventOptions, A as UsePublicEventReturn, D as UsePublicFileDisplayOptions, C as UsePublicFileDisplayReturn, G as UsePublicRouteParamsReturn, n as clearPublicEventCache, q as clearPublicFileDisplayCache, t as clearPublicLogoCache, z as extractEventCodeFromPath, y as generatePublicRoutePath, o as getPublicEventCacheStats, r as getPublicFileDisplayCacheStats, v as getPublicLogoCacheStats, k as useAppConfig, u as useEventTheme, h as useFormDialog, e as useOrganisationPermissions, f as useOrganisationSecurity, m as usePublicEvent, x as usePublicEventCode, s as usePublicEventLogo, p as usePublicFileDisplay, w as usePublicRouteParams, g as useZodForm } from './usePublicRouteParams-CvnC3d-e.js';
+import { a as StorageUploadOptions, c as StorageUploadResult, e as StorageListOptions, f as StorageListResult, m as StorageFileInfo } from './usePublicRouteParams-CTDELQ7H.js';
+export { O as OrganisationSecurityHook, K as UseAppConfigReturn, U as UseFormDialogOptions, h as UseFormDialogReturn, J as UseOrganisationPermissionsReturn, H as UsePublicEventLogoOptions, G as UsePublicEventLogoReturn, C as UsePublicEventOptions, B as UsePublicEventReturn, E as UsePublicFileDisplayOptions, D as UsePublicFileDisplayReturn, I as UsePublicRouteParamsReturn, o as clearPublicEventCache, r as clearPublicFileDisplayCache, v as clearPublicLogoCache, A as extractEventCodeFromPath, z as generatePublicRoutePath, p as getPublicEventCacheStats, s as getPublicFileDisplayCacheStats, w as getPublicLogoCacheStats, k as useAppConfig, l as useEventTheme, g as useFormDialog, i as useOrganisationPermissions, j as useOrganisationSecurity, n as usePublicEvent, y as usePublicEventCode, t as usePublicEventLogo, q as usePublicFileDisplay, x as usePublicRouteParams, u as useZodForm } from './usePublicRouteParams-CTDELQ7H.js';
 import * as React$1 from 'react';
 import { SortingState, ColumnFiltersState, ExpandedState } from '@tanstack/react-table';
+import { d as DataRecord, g as PerformanceConfig, S as ServerSideConfig, C as ChunkingConfig, i as SearchIndexConfig, h as PaginationMode, k as ServerSideParams, l as ServerSideResponse, A as AutocompleteOptions, m as GooglePlaceAutocompletePrediction, P as ParsedAddress } from './types-Bwgl--Xo.js';
 export { u as useComponentPerformance } from './useComponentPerformance-DE9l5RkL.js';
-import { c as DataRecord, P as PerformanceConfig, S as ServerSideConfig, C as ChunkingConfig, g as SearchIndexConfig, f as PaginationMode, i as ServerSideParams, j as ServerSideResponse } from './types-DUyCRSTj.js';
 import { SupabaseClient } from '@supabase/supabase-js';
-import { F as FileCategory, a as FileReference } from './file-reference-BjR39ktt.js';
+import { D as Database } from './database.generated-DI89OQeI.js';
+import { F as FileCategory, a as FileReference } from './file-reference-D037xOFK.js';
 import 'react-hook-form';
 import 'zod';
 import './event-CW5YB_2p.js';
 import './core-CUElvH_C.js';
-import './database.generated-CBmg2950.js';
 
 /**
  * @file Error Handling Stubs
@@ -227,6 +227,64 @@ declare function useDataTableState(options: UseDataTableStateOptions): {
     };
 };
 
+/**
+ * @file Address Autocomplete Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/AddressAutocomplete
+ * @since 0.1.0
+ *
+ * Hook for managing Google Places API autocomplete functionality.
+ * Provides debounced input, caching, and address selection.
+ */
+
+interface UseAddressAutocompleteOptions {
+    /** Google Places API options */
+    autocompleteOptions?: AutocompleteOptions;
+    /** Debounce delay in milliseconds (default: 300) */
+    debounceDelay?: number;
+    /** Enable caching (default: true) */
+    cacheEnabled?: boolean;
+    /** Cache TTL configuration */
+    cacheTTL?: {
+        /** Autocomplete cache TTL in seconds (default: 3600 = 1 hour) */
+        autocomplete?: number;
+        /** Place details cache TTL in seconds (default: 86400 = 24 hours) */
+        placeDetails?: number;
+    };
+}
+interface UseAddressAutocompleteReturn {
+    /** Array of autocomplete suggestions */
+    suggestions: GooglePlaceAutocompletePrediction[];
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: Error | null;
+    /** Select an address by place_id */
+    selectAddress: (placeId: string) => Promise<ParsedAddress | null>;
+    /** Get address by place_id (uses cache) */
+    getAddressByPlaceId: (placeId: string) => Promise<ParsedAddress | null>;
+    /** Clear suggestions */
+    clearSuggestions: () => void;
+}
+/**
+ * Hook for Google Places API autocomplete with caching
+ *
+ * @param apiKey - Google Places API key
+ * @param inputValue - Current input value
+ * @param options - Hook configuration options
+ * @returns Autocomplete state and functions
+ *
+ * @example
+ * ```tsx
+ * const { suggestions, isLoading, selectAddress } = useAddressAutocomplete(
+ *   apiKey,
+ *   inputValue,
+ *   { debounceDelay: 300, cacheEnabled: true }
+ * );
+ * ```
+ */
+declare function useAddressAutocomplete(apiKey: string, inputValue: string, options?: UseAddressAutocompleteOptions): UseAddressAutocompleteReturn;
+
 /**
  * @file useSecureDataAccess Hook
  * @package @jmruthers/pace-core
@@ -359,6 +417,86 @@ declare function usePerformanceMonitor(componentName: string, enabled?: boolean,
     endMeasurement: () => void;
 };
 
+/**
+ * Query Result Caching Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/QueryCache
+ * @since 2.0.0
+ *
+ * Provides in-memory caching for frequently accessed data to eliminate duplicate queries.
+ * Useful for caching user profiles, app pages, and other relatively static data.
+ */
+
+interface UseQueryCacheOptions {
+    /** Time to live in seconds (default: 300 = 5 minutes) */
+    ttl?: number;
+    /** Whether to enable caching (default: true) */
+    enabled?: boolean;
+}
+interface UseQueryCacheReturn {
+    /** Get cached query result or fetch if not cached */
+    getCachedQuery: <T>(table: string, filterKey: string, filterValue: string, fetchFn: () => Promise<T>, options?: UseQueryCacheOptions) => Promise<T>;
+    /** Invalidate a specific cached query */
+    invalidateQuery: (table: string, filterKey: string, filterValue: string) => void;
+    /** Clear all cached queries */
+    clearCache: () => void;
+    /** Get cache statistics */
+    getCacheStats: () => {
+        size: number;
+        keys: string[];
+    };
+}
+/**
+ * Hook for query result caching
+ *
+ * Provides caching for frequently accessed data to eliminate duplicate queries.
+ * Automatically handles cache expiration and cleanup.
+ *
+ * @param supabase - Supabase client (optional, can be passed in fetchFn)
+ * @returns Query cache utilities
+ *
+ * @example
+ * ```tsx
+ * const { getCachedQuery } = useQueryCache(supabase);
+ *
+ * const person = await getCachedQuery(
+ *   'pace_person',
+ *   'user_id',
+ *   userId,
+ *   async () => {
+ *     const { data } = await supabase
+ *       .from('pace_person')
+ *       .select('id, first_name, last_name, email')
+ *       .eq('user_id', userId)
+ *       .single();
+ *     return data;
+ *   },
+ *   { ttl: 300 } // 5 minutes
+ * );
+ * ```
+ */
+declare function useQueryCache(supabase?: SupabaseClient<Database>): UseQueryCacheReturn;
+/**
+ * Pre-configured cache helpers for common queries
+ */
+declare const queryCacheHelpers: {
+    /**
+     * Cache pace_person queries by user_id
+     * TTL: 5 minutes
+     */
+    pacePersonByUserId: <T>(supabase: SupabaseClient<Database>, userId: string, fetchFn: () => Promise<T>) => Promise<T>;
+    /**
+     * Cache pace_member queries by person_id
+     * TTL: 5 minutes
+     */
+    paceMemberByPersonId: <T>(supabase: SupabaseClient<Database>, personId: string, fetchFn: () => Promise<T>) => Promise<T>;
+    /**
+     * Cache rbac_app_pages queries by app_id
+     * TTL: 15 minutes (app pages are relatively static)
+     */
+    rbacAppPagesByAppId: <T>(supabase: SupabaseClient<Database>, appId: string, fetchFn: () => Promise<T>) => Promise<T>;
+};
+
 /**
  * @file File Display Hook (Authenticated)
  * @package @jmruthers/pace-core
@@ -459,6 +597,83 @@ declare function getFileDisplayCacheStats(): {
  */
 declare function invalidateFileDisplayCache(table_name: string, record_id: string, organisation_id: string, category?: FileCategory): void;
 
+/**
+ * @file File URL Cache Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks
+ *
+ * Centralized caching hook for file URLs to prevent duplicate requests
+ * and improve performance across components.
+ *
+ * Features:
+ * - TTL-based caching matching signed URL expiration (3600s)
+ * - Automatic cache cleanup
+ * - Supports both public and signed URLs
+ * - Thread-safe cache operations
+ *
+ * @example
+ * ```tsx
+ * import { useFileUrlCache } from '@jmruthers/pace-core';
+ *
+ * function MyComponent() {
+ *   const { getUrl, setUrl, clearCache } = useFileUrlCache();
+ *
+ *   const url = await getUrl(fileReference, supabase, organisationId);
+ *   return <img src={url} alt="File" />;
+ * }
+ * ```
+ */
+
+interface UseFileUrlCacheReturn {
+    /**
+     * Get URL for a file reference, using cache if available
+     * @param fileReference - File reference to get URL for
+     * @param supabase - Supabase client instance
+     * @param organisationId - Organisation ID for signed URLs
+     * @param ttl - Time to live in milliseconds (default: 3600000 = 1 hour)
+     * @returns Promise resolving to URL string or null
+     */
+    getUrl: (fileReference: FileReference, supabase: SupabaseClient, organisationId: string, ttl?: number) => Promise<string | null>;
+    /**
+     * Set URL in cache
+     * @param fileReference - File reference
+     * @param url - URL to cache
+     * @param ttl - Time to live in milliseconds (default: 3600000 = 1 hour)
+     */
+    setUrl: (fileReference: FileReference, url: string, ttl?: number) => void;
+    /**
+     * Get URL from cache without generating if missing
+     * @param fileReference - File reference
+     * @returns Cached URL or null if not in cache or expired
+     */
+    getCachedUrl: (fileReference: FileReference) => string | null;
+    /**
+     * Clear cache for a specific file reference
+     * @param fileReference - File reference to clear
+     */
+    clearFile: (fileReference: FileReference) => void;
+    /**
+     * Clear all cached URLs
+     */
+    clearCache: () => void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats: () => {
+        size: number;
+        maxSize: number;
+    };
+}
+/**
+ * Hook for centralized file URL caching
+ *
+ * This hook provides a shared cache for file URLs across all components,
+ * preventing duplicate requests for the same file.
+ *
+ * @returns Cache operations and utilities
+ */
+declare function useFileUrlCache(): UseFileUrlCacheReturn;
+
 /**
  * React hook for storage operations
  */
@@ -505,4 +720,48 @@ declare function useFileUpload({ supabase, appName, orgId }: UseStorageOptions):
     uploadError: string | null;
 };
 
-export { type SecureDataAccessReturn, type UseDataTablePerformanceOptions, type UseDataTablePerformanceReturn, type UseFileDisplayOptions, type UseFileDisplayReturn, type UseStorageOptions, type UseStorageReturn, clearFileDisplayCache, getFileDisplayCacheStats, invalidateFileDisplayCache, useDataTablePerformance, useDataTableState, useDebounce, useFileDisplay, useFileUpload, useFocusManagement, useFocusTrap, useIsMobile, useKeyboardShortcuts, usePerformanceMonitor, useSecureDataAccess, useStorage };
+/**
+ * @file usePreventTabReload Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks
+ * @since 0.6.0
+ *
+ * Prevents full page reloads when switching browser tabs.
+ * Handles browser back-forward cache (bfcache) restoration and tab visibility changes.
+ */
+interface UsePreventTabReloadOptions {
+    /**
+     * Whether to enable the prevention logic
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Grace period in milliseconds to wait after tab becomes visible
+     * before allowing any potential reloads
+     * @default 2000
+     */
+    gracePeriodMs?: number;
+}
+/**
+ * Hook to prevent full page reloads when switching browser tabs.
+ *
+ * This hook handles:
+ * - Browser back-forward cache (bfcache) restoration
+ * - Tab visibility changes
+ * - Prevents unwanted page reloads when returning to a tab
+ *
+ * @param options - Configuration options
+ *
+ * @example
+ * ```tsx
+ * import { usePreventTabReload } from '@jmruthers/pace-core';
+ *
+ * function MyComponent() {
+ *   usePreventTabReload();
+ *   // Component code...
+ * }
+ * ```
+ */
+declare function usePreventTabReload(options?: UsePreventTabReloadOptions): void;
+
+export { type SecureDataAccessReturn, type UseAddressAutocompleteOptions, type UseAddressAutocompleteReturn, type UseDataTablePerformanceOptions, type UseDataTablePerformanceReturn, type UseFileDisplayOptions, type UseFileDisplayReturn, type UseFileUrlCacheReturn, type UsePreventTabReloadOptions, type UseQueryCacheOptions, type UseQueryCacheReturn, type UseStorageOptions, type UseStorageReturn, clearFileDisplayCache, getFileDisplayCacheStats, invalidateFileDisplayCache, queryCacheHelpers, useAddressAutocomplete, useDataTablePerformance, useDataTableState, useDebounce, useFileDisplay, useFileUpload, useFileUrlCache, useFocusManagement, useFocusTrap, useIsMobile, useKeyboardShortcuts, usePerformanceMonitor, usePreventTabReload, useQueryCache, useSecureDataAccess, useStorage };