@jmruthers/pace-core 0.5.180 → 0.5.182

package/src/components/FileUpload/FileUpload.tsx

@@ -1,5 +1,11 @@
-// File Upload Component
-// Provides a file upload interface using the file reference system
+/**
+ * @file File Upload Component
+ * @package @jmruthers/pace-core
+ * @module Components/FileUpload
+ * 
+ * Provides a file upload interface using the file reference system.
+ * Supports drag-and-drop, file validation, progress tracking, and accessibility.
+ */
 
 import React, { useState, useCallback, useRef, useEffect, useMemo } from 'react';
 import { SupabaseClient } from '@supabase/supabase-js';
@@ -7,6 +13,7 @@ import { FileCategory, FileUploadResult, UploadProgress } from '../../types/file
 import { useFileReference } from '../../hooks/useFileReference';
 import { getCurrentAppName } from '../../utils/app/appNameResolver';
 import { getAppId } from '../../utils/app/appIdResolver';
+import { assertAppId } from '../../types/core';
 
 export interface FileUploadProps {
   supabase: SupabaseClient;
@@ -275,7 +282,7 @@ export function FileUpload({
           table_name,
           record_id,
           organisation_id,
-          app_id: resolvedAppId,
+          app_id: resolvedAppId ? assertAppId(resolvedAppId) : assertAppId(''),
           category,
           is_public: isPublic
         }, file);
@@ -429,11 +436,21 @@ export function FileUpload({
   return (
     <div className={`space-y-4 ${className}`}>
       <div
+        role="button"
+        tabIndex={isDisabled ? -1 : 0}
+        aria-label="File upload area"
+        aria-disabled={isDisabled}
         className={`relative border-2 border-dashed rounded-lg p-6 text-center transition-colors ${dragClasses} ${disabledClasses}`}
         onDragOver={handleDragOver}
         onDragLeave={handleDragLeave}
         onDrop={handleDrop}
         onClick={!isDisabled ? handleClick : undefined}
+        onKeyDown={!isDisabled ? (e) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            handleClick();
+          }
+        } : undefined}
       >
         {children || (
           <div className="space-y-2">
@@ -468,8 +485,13 @@ export function FileUpload({
         )}
         
         {isUploading && !showProgress && (
-          <div className="absolute inset-0 bg-white bg-opacity-75 flex items-center justify-center">
-            <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-main-500"></div>
+          <div 
+            className="absolute inset-0 bg-white bg-opacity-75 flex items-center justify-center"
+            role="status"
+            aria-live="polite"
+            aria-label="Uploading file"
+          >
+            <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-main-500" aria-hidden="true"></div>
           </div>
         )}
       </div>
@@ -549,7 +571,12 @@ export function FileUpload({
                     <span className="text-acc-500 text-xl">✕</span>
                   )}
                   {isUploading && (
-                    <div className="animate-spin rounded-full h-5 w-5 border-b-2 border-main-500"></div>
+                    <div 
+                      className="animate-spin rounded-full h-5 w-5 border-b-2 border-main-500"
+                      role="status"
+                      aria-label="Uploading"
+                      aria-hidden="true"
+                    ></div>
                   )}
                 </div>
               </div>
@@ -559,12 +586,20 @@ export function FileUpload({
       )}
       
       {appIdError && (
-        <div className="p-3 bg-acc-50 border border-acc-200 rounded-lg text-sm text-acc-600">
+        <div 
+          className="p-3 bg-acc-50 border border-acc-200 rounded-lg text-sm text-acc-600"
+          role="alert"
+          aria-live="assertive"
+        >
           {appIdError}
         </div>
       )}
       {error && (
-        <div className="p-3 bg-acc-50 border border-acc-200 rounded-lg text-sm text-acc-600">
+        <div 
+          className="p-3 bg-acc-50 border border-acc-200 rounded-lg text-sm text-acc-600"
+          role="alert"
+          aria-live="assertive"
+        >
           {error}
         </div>
       )}

package/src/components/Footer/Footer.test.tsx

@@ -8,23 +8,28 @@
  * Tests rendering, props handling, navigation links, and accessibility.
  */
 
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { render, screen } from '@testing-library/react';
 import { Footer, FooterProps } from './Footer';
 import { renderWithProviders } from '../../__tests__/helpers/test-utils';
 
-// Mock the current year for consistent testing
-const mockCurrentYear = 2024;
 vi.mock('../../utils/core/cn', () => ({
   cn: (...classes: (string | undefined)[]) => classes.filter(Boolean).join(' ')
 }));
 
-// Mock Date for consistent year testing
-const mockDate = new Date('2024-01-01');
-vi.spyOn(global, 'Date').mockImplementation(() => mockDate as any);
+// Mock Date for consistent year testing using fake timers
+const mockDate = new Date('2024-01-01T00:00:00Z');
 
 describe('Footer Component', () => {
-    describe('Rendering', () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ now: mockDate });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('Rendering', () => {
     it('renders with default props', () => {
       renderWithProviders(<Footer />);
       
@@ -43,13 +48,13 @@ describe('Footer Component', () => {
     it('renders with default company name and year', () => {
       renderWithProviders(<Footer />);
       
-      expect(screen.getByText(/© Copyright 2022–2025 all rights reserved, Solvera Solutions Pty Ltd\./)).toBeInTheDocument();
+      expect(screen.getByText(/© Copyright 2022–2024 all rights reserved, Solvera Solutions Pty Ltd\./)).toBeInTheDocument();
     });
 
     it('renders with custom company name', () => {
       renderWithProviders(<Footer companyName="Test Company Inc." />);
       
-      expect(screen.getByText(/© Copyright 2022–2025 all rights reserved, Test Company Inc\./)).toBeInTheDocument();
+      expect(screen.getByText(/© Copyright 2022–2024 all rights reserved, Test Company Inc\./)).toBeInTheDocument();
     });
 
     it('renders with custom year', () => {
@@ -271,7 +276,7 @@ describe('Footer Component', () => {
     it('handles empty string company name', () => {
       renderWithProviders(<Footer companyName="" />);
       
-      expect(screen.getByText(/© Copyright 2022–2025 all rights reserved, \./)).toBeInTheDocument();
+      expect(screen.getByText(/© Copyright 2022–2024 all rights reserved, \./)).toBeInTheDocument();
     });
 
     it('handles zero year', () => {
@@ -296,20 +301,20 @@ describe('Footer Component', () => {
       renderWithProviders(<Footer copyright="" />);
       
       // When copyright is empty string, it falls back to default copyright
-      expect(screen.getByText(/© Copyright 2022–2025 all rights reserved, Solvera Solutions Pty Ltd\./)).toBeInTheDocument();
+      expect(screen.getByText(/© Copyright 2022–2024 all rights reserved, Solvera Solutions Pty Ltd\./)).toBeInTheDocument();
     });
 
     it('handles special characters in company name', () => {
       renderWithProviders(<Footer companyName="Company & Co. (Ltd.)" />);
       
-      expect(screen.getByText(/© Copyright 2022–2025 all rights reserved, Company & Co\. \(Ltd\.\)\./)).toBeInTheDocument();
+      expect(screen.getByText(/© Copyright 2022–2024 all rights reserved, Company & Co\. \(Ltd\.\)\./)).toBeInTheDocument();
     });
 
     it('handles very long company name', () => {
       const longName = 'A'.repeat(100);
       renderWithProviders(<Footer companyName={longName} />);
       
-      expect(screen.getByText(new RegExp(`© Copyright 2022–2025 all rights reserved, ${longName}\\.`))).toBeInTheDocument();
+      expect(screen.getByText(new RegExp(`© Copyright 2022–2024 all rights reserved, ${longName}\\.`))).toBeInTheDocument();
     });
 
     it('handles links with special characters', () => {
@@ -344,7 +349,7 @@ describe('Footer Component', () => {
       renderWithProviders(<Footer />);
       
       expect(screen.getByText(/Solvera Solutions Pty Ltd/)).toBeInTheDocument();
-      expect(screen.getByText(/2025/)).toBeInTheDocument();
+      expect(screen.getByText(/2024/)).toBeInTheDocument();
     });
 
     it('overrides default values when props are provided', () => {

package/src/components/Form/Form.test.tsx

@@ -9,7 +9,7 @@
  */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { render, screen, fireEvent, waitFor, act } from '@testing-library/react';
+import { render, screen, waitFor, act } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { z } from 'zod';
 import { Form, FormField } from './index';
@@ -94,17 +94,42 @@ describe('Form Component', () => {
     it('renders with default values', () => {
       const onSubmit = vi.fn();
       const defaultValues = { name: 'John', email: 'john@example.com' };
-      
+
       renderWithProviders(
         <Form onSubmit={onSubmit} defaultValues={defaultValues}>
           <FormField name="name" label="Name" />
           <FormField name="email" label="Email" />
         </Form>
       );
-      
+
       expect(screen.getByDisplayValue('John')).toBeInTheDocument();
       expect(screen.getByDisplayValue('john@example.com')).toBeInTheDocument();
     });
+
+    it('shares live form state with render prop children', async () => {
+      const onSubmit = vi.fn();
+
+      renderWithProviders(
+        <Form onSubmit={onSubmit} defaultValues={{ name: '' }}>
+          {({ formState, watch }) => (
+            <>
+              <span data-testid="dirty-flag">{formState.isDirty ? 'dirty' : 'pristine'}</span>
+              <span data-testid="watched-value">{watch('name')}</span>
+              <FormField name="name" label="Name" />
+            </>
+          )}
+        </Form>
+      );
+
+      const input = screen.getByLabelText('Name');
+      expect(screen.getByTestId('dirty-flag')).toHaveTextContent('pristine');
+      await user.type(input, 'Jane');
+
+      await waitFor(() => {
+        expect(screen.getByTestId('dirty-flag')).toHaveTextContent('dirty');
+        expect(screen.getByTestId('watched-value')).toHaveTextContent('Jane');
+      });
+    });
   });
 
   describe('Form Submission', () => {
@@ -383,17 +408,37 @@ describe('FormField Component', () => {
 
     it('renders with placeholder', () => {
       const onSubmit = vi.fn();
-      
+
       renderWithProviders(
         <Form onSubmit={onSubmit}>
           <FormField name="test" label="Test Field" placeholder="Enter text" />
         </Form>
       );
-      
+
       const input = screen.getByLabelText('Test Field');
       expect(input).toHaveAttribute('placeholder', 'Enter text');
     });
 
+    it('applies arbitrary input props and forwards events', async () => {
+      const onSubmit = vi.fn();
+      const handleFocus = vi.fn();
+
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          <FormField
+            name="test"
+            label="Test Field"
+            inputProps={{ autoComplete: 'off', onFocus: handleFocus }}
+          />
+        </Form>
+      );
+
+      const input = screen.getByLabelText('Test Field');
+      expect(input).toHaveAttribute('autocomplete', 'off');
+      await user.click(input);
+      expect(handleFocus).toHaveBeenCalled();
+    });
+
     it('renders with custom className', () => {
       const onSubmit = vi.fn();
       
@@ -518,17 +563,54 @@ describe('FormField Component', () => {
         </Form>
       );
       
-      expect(renderFn).toHaveBeenCalledWith({
-        field: expect.objectContaining({
-          name: 'test',
-          value: undefined,
-          onChange: expect.any(Function),
-          onBlur: expect.any(Function),
-          ref: expect.any(Function)
+      expect(renderFn).toHaveBeenCalledWith(
+        expect.objectContaining({
+          field: expect.objectContaining({
+            name: 'test',
+            value: undefined,
+            onChange: expect.any(Function),
+            onBlur: expect.any(Function),
+            ref: expect.any(Function)
+          }),
+          fieldState: expect.objectContaining({
+            error: undefined,
+            invalid: false,
+            isDirty: false,
+            isTouched: false,
+            isValidating: false
+          }),
+          formState: expect.any(Object)
         })
-      });
+      );
       expect(screen.getByTestId('custom-input')).toBeInTheDocument();
     });
+
+    it('surfaces validation errors through custom render props', async () => {
+      const onSubmit = vi.fn();
+
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          <FormField
+            name="test"
+            label="Test Field"
+            validation={{ required: 'Custom error' }}
+            render={({ field, fieldState }) => (
+              <div>
+                <input data-testid="custom-render-input" {...field} />
+                <span data-testid="custom-render-error">{fieldState.error?.message}</span>
+              </div>
+            )}
+          />
+          <button type="submit">Submit</button>
+        </Form>
+      );
+
+      await user.click(screen.getByRole('button', { name: 'Submit' }));
+
+      await waitFor(() => {
+        expect(screen.getByTestId('custom-render-error')).toHaveTextContent('Custom error');
+      });
+    });
   });
 
   describe('Accessibility', () => {
@@ -611,7 +693,7 @@ describe('Integration', () => {
     expect(onError).not.toHaveBeenCalled();
   });
 
-  it('handles form errors with error summary', async () => {
+  it('handles form validation errors', async () => {
     const onSubmit = vi.fn();
     const onError = vi.fn();
     const schema = z.object({

package/src/components/Form/Form.tsx

@@ -72,10 +72,11 @@
  */
 
 import React from 'react';
-import { useForm, FormProvider, UseFormReturn, FieldValues, DefaultValues, SubmitHandler, SubmitErrorHandler } from 'react-hook-form';
+import { useForm, FormProvider, UseFormReturn, FieldValues, DefaultValues, SubmitHandler, SubmitErrorHandler, useFormContext, Controller, FieldPath, ControllerRenderProps, ControllerFieldState, UseFormStateReturn } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
 import { cn } from '../../utils/core/cn';
+import { Label } from '../Label';
 
 /**
  * Props for the Form component
@@ -164,3 +165,211 @@ export function Form<TFieldValues extends FieldValues = FieldValues>({
     </FormProvider>
   );
 }
+
+/**
+ * Props for the FormField component
+ */
+export interface FormFieldProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
+> {
+  /**
+   * Field name
+   */
+  name: TName;
+  
+  /**
+   * Field label
+   */
+  label?: string;
+  
+  /**
+   * Field type
+   */
+  type?: string;
+  
+  /**
+   * Placeholder text
+   */
+  placeholder?: string;
+  
+  /**
+   * Additional props for the input
+   */
+  inputProps?: React.InputHTMLAttributes<HTMLInputElement>;
+  
+  /**
+   * Validation rules
+   */
+  validation?: {
+    required?: boolean;
+    pattern?: {
+      value: RegExp;
+      message: string;
+    };
+    minLength?: {
+      value: number;
+      message: string;
+    };
+    maxLength?: {
+      value: number;
+      message: string;
+    };
+  };
+  
+  /**
+   * Custom render function
+   */
+  render?: (props: {
+    field: ControllerRenderProps<TFieldValues, TName>;
+    fieldState: ControllerFieldState;
+    formState: UseFormStateReturn<TFieldValues>;
+  }) => React.ReactElement;
+  
+  /**
+   * Test ID
+   */
+  'data-testid'?: string;
+  
+  /**
+   * Class name
+   */
+  className?: string;
+}
+
+/**
+ * FormField component for React Hook Form integration
+ * 
+ * A flexible form field component that integrates with React Hook Form and provides
+ * built-in validation, error handling, and accessibility features.
+ * 
+ * Features:
+ * - React Hook Form integration with Controller
+ * - Built-in validation with error display
+ * - Accessible labels and error messages
+ * - Custom render function support
+ * - TypeScript support with generic field paths
+ * - Consistent styling with error states
+ * - Test ID support for testing
+ * - Flexible input types and props
+ * 
+ * @template TFieldValues - The type of form field values
+ * @template TName - The type of the field name (must be a valid field path)
+ * @param props - Form field configuration and validation
+ * @returns JSX.Element - The rendered form field with validation
+ * 
+ * @example
+ * ```tsx
+ * // Basic text field
+ * <FormField
+ *   name="username"
+ *   label="Username"
+ *   placeholder="Enter your username"
+ *   validation={{ required: true }}
+ * />
+ * 
+ * // Email field with custom validation
+ * <FormField
+ *   name="email"
+ *   label="Email Address"
+ *   type="email"
+ *   validation={{
+ *     required: true,
+ *     pattern: {
+ *       value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i,
+ *       message: "Invalid email address"
+ *     }
+ *   }}
+ * />
+ * 
+ * // Custom render function
+ * <FormField
+ *   name="avatar"
+ *   label="Profile Picture"
+ *   render={({ field }) => (
+ *     <input
+ *       {...field}
+ *       type="file"
+ *       accept="image/*"
+ *     />
+ *   )}
+ * />
+ * ```
+ * 
+ * @accessibility
+ * - Proper label association with htmlFor
+ * - Error messages with role="alert"
+ * - Required field indicators
+ * - Focus management
+ * - Screen reader friendly error announcements
+ * - Keyboard navigation support
+ */
+export function FormField<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
+>({
+  name,
+  label,
+  type = "text",
+  placeholder,
+  inputProps,
+  validation,
+  render,
+  'data-testid': testId,
+  className,
+}: FormFieldProps<TFieldValues, TName>) {
+  const { control, formState: { errors } } = useFormContext<TFieldValues>();
+  const fieldError = errors[name];
+
+  // Safely extract error message
+  const errorMessage = fieldError && typeof fieldError === 'object' && 'message' in fieldError 
+    ? String(fieldError.message) 
+    : undefined;
+
+  return (
+    <div className={cn("space-y-2", className)}>
+      {label && (
+        <Label htmlFor={name}>
+          {label}
+          {validation?.required && (
+            <span className="text-destructive ml-1" aria-label="required">
+              *
+            </span>
+          )}
+        </Label>
+      )}
+      
+      <Controller
+        name={name}
+        control={control}
+        rules={validation}
+        render={(props) => {
+          if (render) {
+            return render(props);
+          }
+          
+          return (
+            <input
+              {...props.field}
+              id={name}
+              type={type}
+              placeholder={placeholder}
+              data-testid={testId}
+              className={cn(
+                "flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+                fieldError && "border-destructive focus-visible:ring-destructive"
+              )}
+              {...inputProps}
+            />
+          );
+        }}
+      />
+      
+      {errorMessage && (
+        <p className="text-destructive" role="alert">
+          {errorMessage}
+        </p>
+      )}
+    </div>
+  );
+}

package/src/components/Form/index.ts

@@ -5,10 +5,6 @@
  * @since 0.1.0
  */
 
-// Main Form component
-export { Form } from './Form';
-export type { FormProps } from './Form';
-
-// Form Field component
-export { FormField } from './FormField';
-export type { FormFieldProps } from './FormField';
+// Form components (Form and FormField are in the same file)
+export { Form, FormField } from './Form';
+export type { FormProps, FormFieldProps } from './Form';