@jmruthers/pace-core 0.5.184 → 0.5.186

package/src/components/DateTimeField/DateTimeField.tsx

@@ -0,0 +1,232 @@
+/**
+ * @file DateTimeField Component
+ * @package @jmruthers/pace-core
+ * @module Components/DateTimeField
+ * @since 0.1.0
+ *
+ * Form input component for datetime values with timezone support.
+ * Handles UTC ↔ timezone conversion automatically.
+ *
+ * Features:
+ * - Automatic UTC ↔ timezone conversion
+ * - Prevents unwanted conversions during user editing
+ * - Shows timezone information when not UTC
+ * - Supports both ISO string and Date object values
+ * - Uses native datetime-local input type
+ * - Accessible form field with proper labels
+ *
+ * @example
+ * ```tsx
+ * import { DateTimeField } from '@jmruthers/pace-core/components';
+ * import { useState } from 'react';
+ *
+ * function EventForm() {
+ *   const [startTime, setStartTime] = useState<string>();
+ *
+ *   return (
+ *     <DateTimeField
+ *       label="Start Time"
+ *       value={startTime}
+ *       onChange={setStartTime}
+ *       timezone="America/New_York"
+ *       required
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @accessibility
+ * - Proper label association with htmlFor
+ * - Required field indicators
+ * - Screen reader friendly
+ * - Keyboard navigation support
+ * - Focus management
+ */
+
+import * as React from 'react';
+import { format, parse } from 'date-fns';
+import { Label } from '../Label';
+import { Input } from '../Input';
+import { cn } from '../../utils/core/cn';
+import { toZonedTime, fromZonedTime, getUserTimeZone } from '../../utils/timezone';
+
+/**
+ * Props for the DateTimeField component
+ */
+export interface DateTimeFieldProps {
+  /**
+   * Field label
+   */
+  label: string;
+  /**
+   * UTC date value (ISO string, Date object, or undefined)
+   */
+  value: string | Date | undefined;
+  /**
+   * Change handler that receives UTC value (ISO string or Date object)
+   */
+  onChange: (value: string | Date | undefined) => void;
+  /**
+   * Target timezone for display (default: 'UTC')
+   */
+  timezone?: string;
+  /**
+   * Whether the field is required
+   */
+  required?: boolean;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+  /**
+   * If true, onChange returns Date object instead of ISO string
+   */
+  returnAsDate?: boolean;
+  /**
+   * Input id (auto-generated if not provided)
+   */
+  id?: string;
+  /**
+   * Helper text to display below the label
+   */
+  helperText?: string;
+  /**
+   * Error message to display
+   */
+  error?: string;
+}
+
+/**
+ * DateTimeField component
+ * Form input for datetime values with automatic timezone conversion
+ *
+ * @param props - DateTimeField configuration
+ * @returns JSX.Element - The rendered datetime field
+ */
+export function DateTimeField({
+  label,
+  value,
+  onChange,
+  timezone = 'UTC',
+  required = false,
+  className,
+  returnAsDate = false,
+  id,
+  helperText,
+  error
+}: DateTimeFieldProps) {
+  const [isEditing, setIsEditing] = React.useState(false);
+  const inputRef = React.useRef<HTMLInputElement>(null);
+  const fieldId = id || `datetime-field-${React.useId()}`;
+
+  // Convert UTC value to timezone for display
+  const getDisplayValue = React.useCallback((): string => {
+    if (!value) {
+      return '';
+    }
+
+    try {
+      let dateObj: Date;
+      if (typeof value === 'string') {
+        dateObj = new Date(value);
+      } else {
+        dateObj = value;
+      }
+
+      if (!dateObj || isNaN(dateObj.getTime())) {
+        return '';
+      }
+
+      // Convert UTC to timezone
+      const zonedDate = toZonedTime(dateObj, timezone);
+
+      // Format for datetime-local input (YYYY-MM-DDTHH:mm)
+      return format(zonedDate, "yyyy-MM-dd'T'HH:mm");
+    } catch {
+      return '';
+    }
+  }, [value, timezone]);
+
+  const displayValue = isEditing ? undefined : getDisplayValue();
+
+  // Handle input change
+  const handleChange = React.useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    setIsEditing(true);
+    const inputValue = e.target.value;
+
+    if (!inputValue) {
+      onChange(undefined);
+      return;
+    }
+
+    try {
+      // Parse the datetime-local value (in timezone)
+      const localDate = parse(inputValue, "yyyy-MM-dd'T'HH:mm", new Date());
+
+      if (isNaN(localDate.getTime())) {
+        onChange(undefined);
+        return;
+      }
+
+      // Convert from timezone to UTC
+      const utcDate = fromZonedTime(localDate, timezone);
+
+      // Return as ISO string or Date object
+      if (returnAsDate) {
+        onChange(utcDate);
+      } else {
+        onChange(utcDate.toISOString());
+      }
+    } catch {
+      onChange(undefined);
+    }
+  }, [timezone, returnAsDate, onChange]);
+
+  // Handle blur to stop editing mode
+  const handleBlur = React.useCallback(() => {
+    setIsEditing(false);
+  }, []);
+
+  // Get timezone display text
+  const getTimezoneDisplay = React.useCallback((): string => {
+    if (timezone === 'UTC') {
+      return '';
+    }
+
+    const userTz = getUserTimeZone();
+    if (timezone === userTz) {
+      return 'Local';
+    }
+
+    return timezone;
+  }, [timezone]);
+
+  const timezoneDisplay = getTimezoneDisplay();
+
+  return (
+    <div className={cn('space-y-2', className)}>
+      <Label htmlFor={fieldId} required={required} helperText={helperText} error={error}>
+        {label}
+      </Label>
+      <div className="relative">
+        <Input
+          ref={inputRef}
+          id={fieldId}
+          type="datetime-local"
+          value={displayValue}
+          onChange={handleChange}
+          onBlur={handleBlur}
+          required={required}
+          error={!!error}
+          className="w-full"
+        />
+        {timezoneDisplay && (
+          <span className="absolute right-3 top-1/2 -translate-y-1/2 text-sm text-muted-foreground pointer-events-none">
+            {timezoneDisplay}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}
+

package/src/components/DateTimeField/README.md

@@ -0,0 +1,148 @@
+# DateTimeField Component
+
+Form input component for datetime values with automatic UTC ↔ timezone conversion.
+
+## Overview
+
+The `DateTimeField` component provides a datetime input field that automatically handles conversion between UTC (for storage) and a specified timezone (for display). It prevents unwanted conversions during user editing and displays timezone information when not using UTC.
+
+## Features
+
+- Automatic UTC ↔ timezone conversion
+- Prevents unwanted conversions during user editing
+- Shows timezone information when not UTC
+- Supports both ISO string and Date object values
+- Uses native `datetime-local` input type
+- Accessible form field with proper labels
+- Error state support
+- Helper text support
+
+## Usage
+
+### Basic Example
+
+```tsx
+import { DateTimeField } from '@jmruthers/pace-core/components';
+import { useState } from 'react';
+
+function EventForm() {
+  const [startTime, setStartTime] = useState<string>();
+
+  return (
+    <DateTimeField
+      label="Start Time"
+      value={startTime}
+      onChange={setStartTime}
+      timezone="America/New_York"
+      required
+    />
+  );
+}
+```
+
+### With Date Object
+
+```tsx
+import { DateTimeField } from '@jmruthers/pace-core/components';
+import { useState } from 'react';
+
+function EventForm() {
+  const [startTime, setStartTime] = useState<Date>();
+
+  return (
+    <DateTimeField
+      label="Start Time"
+      value={startTime}
+      onChange={setStartTime}
+      timezone="America/New_York"
+      returnAsDate
+    />
+  );
+}
+```
+
+### With Error State
+
+```tsx
+<DateTimeField
+  label="Start Time"
+  value={startTime}
+  onChange={setStartTime}
+  timezone="America/New_York"
+  error="Please select a valid start time"
+  required
+/>
+```
+
+### With Helper Text
+
+```tsx
+<DateTimeField
+  label="Start Time"
+  value={startTime}
+  onChange={setStartTime}
+  timezone="America/New_York"
+  helperText="Select the event start time in your local timezone"
+/>
+```
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | **required** | Field label |
+| `value` | `string \| Date \| undefined` | - | UTC date value (ISO string, Date object, or undefined) |
+| `onChange` | `(value: string \| Date \| undefined) => void` | **required** | Change handler that receives UTC value |
+| `timezone` | `string` | `'UTC'` | Target timezone for display (IANA timezone string) |
+| `required` | `boolean` | `false` | Whether the field is required |
+| `className` | `string` | - | Additional CSS classes |
+| `returnAsDate` | `boolean` | `false` | If true, onChange returns Date object instead of ISO string |
+| `id` | `string` | - | Input id (auto-generated if not provided) |
+| `helperText` | `string` | - | Helper text to display below the label |
+| `error` | `string` | - | Error message to display |
+
+## Behavior
+
+### Timezone Conversion
+
+The component automatically converts between UTC (for storage) and the specified timezone (for display):
+
+- **Display**: UTC values are converted to the specified timezone for display in the input
+- **Input**: User-entered values (in the timezone) are converted back to UTC before calling `onChange`
+
+### Editing Prevention
+
+The component tracks editing state to prevent unwanted conversions while the user is typing. Conversions only occur when:
+- The component receives a new `value` prop (controlled component)
+- The user finishes editing (blur event)
+
+### Timezone Display
+
+- When `timezone` is `'UTC'`: No timezone indicator is shown
+- When `timezone` matches the user's browser timezone: Shows "Local"
+- When `timezone` is different: Shows the timezone name (e.g., "America/New_York")
+
+## Accessibility
+
+- Proper label association with `htmlFor`
+- Required field indicators for screen readers
+- Error messages with `role="alert"`
+- Keyboard navigation support
+- Focus management
+
+## Edge Cases
+
+- **Invalid dates**: Returns empty string in input, calls `onChange(undefined)`
+- **Null/undefined values**: Displays empty input
+- **Invalid timezone**: Falls back to UTC behavior
+
+## Dependencies
+
+- `date-fns` - Date formatting and parsing
+- `date-fns-tz` - Timezone conversion
+- `@jmruthers/pace-core/components/Label` - Label component
+- `@jmruthers/pace-core/components/Input` - Input component
+- `@jmruthers/pace-core/utils/timezone` - Timezone utilities
+

package/src/components/DateTimeField/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @file DateTimeField Component Exports
+ * @package @jmruthers/pace-core
+ * @module Components/DateTimeField
+ * @since 0.1.0
+ */
+
+export { DateTimeField } from './DateTimeField';
+export type { DateTimeFieldProps } from './DateTimeField';
+

package/src/components/FileUpload/FileUpload.test.tsx

@@ -71,6 +71,8 @@ describe('[component] FileUpload', () => {
     organisation_id: 'org-1',
     app_id: 'app-123',
     category: FileCategory.PROFILE_PHOTOS,
+    folder: 'profile_photos',
+    pageContext: 'test',
     accept: 'image/*',
   } as const;
 

package/src/components/FileUpload/FileUpload.tsx

@@ -22,6 +22,9 @@ export interface FileUploadProps {
   organisation_id: string;
   app_id?: string; // Optional - will be resolved from app name if not provided
   category: FileCategory;
+  folder: string; // Folder name in storage bucket (e.g., 'profile_photos', 'documents')
+  pageContext: string; // The page context where the file upload occurs (e.g., 'configuration', 'forms', 'applications')
+  event_id?: string; // Optional event ID for event-scoped permission checks (required for event-based apps)
   accept?: string;
   maxSize?: number;
   multiple?: boolean;
@@ -50,6 +53,9 @@ export function FileUpload({
   organisation_id,
   app_id,
   category,
+  folder,
+  pageContext,
+  event_id,
   accept = '*/*',
   maxSize = 10 * 1024 * 1024, // 10MB default
   multiple = false,
@@ -284,6 +290,9 @@ export function FileUpload({
           organisation_id,
           app_id: resolvedAppId ? assertAppId(resolvedAppId) : assertAppId(''),
           category,
+          folder,
+          pageContext,
+          event_id,
           is_public: isPublic
         }, file);
 
@@ -381,7 +390,7 @@ export function FileUpload({
         onUploadError?.(errorMessage, file);
       }
     }
-  }, [uploadFile, table_name, record_id, organisation_id, resolvedAppId, category, isPublic, maxSize, onUploadSuccess, onUploadError, onProgress, validateFile, generatePreview, showPreview, appIdError]);
+  }, [uploadFile, table_name, record_id, organisation_id, resolvedAppId, category, folder, isPublic, maxSize, onUploadSuccess, onUploadError, onProgress, validateFile, generatePreview, showPreview, appIdError]);
 
   const handleDragOver = useCallback((e: React.DragEvent) => {
     e.preventDefault();

package/src/components/Header/Header.test.tsx

@@ -60,6 +60,14 @@ vi.mock('../EventSelector', () => ({
   ),
 }));
 
+vi.mock('../OrganisationSelector', () => ({
+  OrganisationSelector: ({ placeholder, className, 'data-testid': testId }: any) => (
+    <div data-testid={testId || 'org-selector'} className={className}>
+      <button>{placeholder}</button>
+    </div>
+  ),
+}));
+
 // Test data
 const mockUser: User = {
   id: '123',
@@ -312,16 +320,8 @@ describe('Header Component', () => {
       expect(screen.getByRole('button', { name: 'Select event' })).toBeInTheDocument();
     });
 
-    it('renders placeholder when showEventSelector is false', () => {
-      const { container } = renderWithProviders(<Header showEventSelector={false} />);
-      
-      const placeholder = container.querySelector('del.invisible');
-      expect(placeholder).toBeInTheDocument();
-      expect(placeholder).toHaveTextContent('Event Selector N/A');
-    });
-
-    it('preserves grid layout when event selector is hidden', () => {
-      const { container } = renderWithProviders(
+    it('preserves layout when event selector is hidden', () => {
+      renderWithProviders(
         <Header 
           showEventSelector={false}
           user={mockUser}
@@ -333,15 +333,47 @@ describe('Header Component', () => {
       expect(nav).toBeInTheDocument();
       expect(nav).toBeVisible();
       
-      // Placeholder should maintain grid structure
-      const placeholder = container.querySelector('del.invisible');
-      expect(placeholder).toBeInTheDocument();
+      // Event selector should not be rendered
+      expect(screen.queryByTestId('event-selector')).not.toBeInTheDocument();
       
       // User menu should still be present and positioned correctly
       expect(screen.getByTestId('user-menu')).toBeInTheDocument();
     });
   });
 
+  // Organisation Selector tests
+  describe('Organisation Selector', () => {
+    it('does not render organisation selector by default', () => {
+      renderWithProviders(<Header />);
+      
+      expect(screen.queryByTestId('org-selector')).not.toBeInTheDocument();
+    });
+
+    it('renders organisation selector when showOrgSelector is true', () => {
+      renderWithProviders(<Header showOrgSelector={true} />);
+      
+      expect(screen.getByTestId('org-selector')).toBeInTheDocument();
+    });
+
+    it('does not render organisation selector when showOrgSelector is false', () => {
+      renderWithProviders(<Header showOrgSelector={false} />);
+      
+      expect(screen.queryByTestId('org-selector')).not.toBeInTheDocument();
+    });
+
+    it('can render both organisation and event selectors together', () => {
+      renderWithProviders(
+        <Header 
+          showOrgSelector={true}
+          showEventSelector={true}
+        />
+      );
+      
+      expect(screen.getByTestId('org-selector')).toBeInTheDocument();
+      expect(screen.getByTestId('event-selector')).toBeInTheDocument();
+    });
+  });
+
   // Custom actions tests
   describe('Custom Actions', () => {
     it('renders custom actions when provided', () => {
@@ -560,7 +592,7 @@ describe('Header Component', () => {
     });
 
     it('renders minimal configuration', () => {
-      const { container } = renderWithProviders(
+      renderWithProviders(
         <Header
           showEventSelector={false}
           showUserMenu={false}
@@ -573,10 +605,7 @@ describe('Header Component', () => {
       expect(screen.queryByTestId('navigation-menu')).not.toBeInTheDocument();
       expect(screen.queryByTestId('event-selector')).not.toBeInTheDocument();
       expect(screen.queryByTestId('user-menu')).not.toBeInTheDocument();
-      
-      // Should have placeholder for event selector
-      const placeholder = container.querySelector('del.invisible');
-      expect(placeholder).toBeInTheDocument();
+      expect(screen.queryByTestId('org-selector')).not.toBeInTheDocument();
     });
   });
 

package/src/components/Header/Header.tsx

@@ -5,13 +5,14 @@
  * @since 0.1.0
  *
  * A comprehensive header component for application layouts with navigation,
- * user menu, event selector, and customizable branding.
+ * user menu, organisation selector, event selector, and customizable branding.
  *
  * Features:
  * - Customizable logo (URL or component)
  * - Clickable logo that routes to dashboard (configurable)
  * - Navigation menu integration
  * - User menu with authentication
+ * - Organisation selector for multi-organisation applications
  * - Event selector for multi-tenant applications
  * - Custom actions support
  * - Responsive design
@@ -82,6 +83,7 @@
  * - Tailwind CSS - Styling
  * - NavigationMenu component
  * - UserMenu component
+ * - OrganisationSelector component
  * - EventSelector component
  */
 
@@ -90,6 +92,7 @@ import { Link } from 'react-router-dom';
 import { User } from '@supabase/supabase-js';
 import { cn } from '../../utils/core/cn';
 import { EventSelector } from '../EventSelector';
+import { OrganisationSelector } from '../OrganisationSelector';
 import { UserMenu } from '../UserMenu';
 import { NavigationMenu } from '../NavigationMenu';
 import type { NavigationItem } from '../NavigationMenu';
@@ -121,6 +124,8 @@ export interface HeaderProps {
   className?: string;
   /** Show/hide event selector */
   showEventSelector?: boolean;
+  /** Show/hide organisation selector */
+  showOrgSelector?: boolean;
   /** Show/hide user menu */
   showUserMenu?: boolean;
   /** Current path for navigation highlighting */
@@ -244,6 +249,7 @@ export function Header({
   userMenu,
   className,
   showEventSelector = true,
+  showOrgSelector = false,
   showUserMenu = true,
   currentPath,
   onNavigate,
@@ -254,7 +260,7 @@ export function Header({
       "w-full border-b border-main-200 h-16 shadow-sm bg-main-100 ",
       className
     )} role="banner">
-      <nav className="px-4 w-[min(var(--app-width),100%)] mx-auto grid grid-cols-[auto_auto_1fr_auto] gap-4 h-full items-center">
+      <nav className="px-4 w-[min(var(--app-width),100%)] mx-auto flex items-center gap-4 h-full">
           {/* Logo */}
           {logo ? (
             logoHref ? (
@@ -311,18 +317,26 @@ export function Header({
           )}
         
 
-        {/* Right side: Event Selector, Actions, and User Menu */}
+        {/* Right side: Organisation Selector, Event Selector, Actions, and User Menu */}
+        <div className="flex items-center gap-4 ml-auto">
+          {/* Organisation Selector */}
+          {showOrgSelector ? (
+            <OrganisationSelector 
+              placeholder="Select organisation" 
+              className="w-64" 
+              data-testid="org-selector"
+              compact={true}
+            />
+          ) : null}
 
           {/* Event Selector */}
           {showEventSelector ? (
             <EventSelector 
               placeholder="Select event" 
-              className="justify-self-end w-96" 
+              className="w-96" 
               data-testid="event-selector" 
             />
-          ) : (
-            <del className="justify-self-end invisible">Event Selector N/A</del>
-          )}
+          ) : null}
           
           {/* Custom Actions */}
           {actions}
@@ -340,6 +354,7 @@ export function Header({
               />
             )
           )}
+        </div>
 
       </nav>
     </header>