@jmruthers/pace-core 0.5.136 → 0.5.137

package/src/components/Dialog/utils/safeHtml.ts

@@ -0,0 +1,185 @@
+/**
+ * @file Safe HTML Utilities for Dialog Component
+ * @package @jmruthers/pace-core
+ * @module Components/Dialog/Utils/safeHtml
+ * @since 0.4.36
+ * 
+ * Utilities for safely rendering HTML content in Dialog components.
+ * Provides sanitization and validation for basic HTML elements.
+ */
+
+/**
+ * Allowed HTML tags for safe rendering in Dialog components
+ */
+const ALLOWED_TAGS = [
+  'p', 'div', 'span', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+  'strong', 'em', 'b', 'i', 'u', 's', 'mark', 'small', 'sub', 'sup',
+  'ul', 'ol', 'li', 'dl', 'dt', 'dd',
+  'blockquote', 'pre', 'code', 'kbd', 'samp',
+  'a', 'br', 'hr',
+  'table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td',
+  'img', 'figure', 'figcaption',
+  'section', 'article', 'aside', 'header', 'footer', 'main', 'nav',
+  'details', 'summary'
+] as const;
+
+/**
+ * Allowed HTML attributes for safe rendering
+ */
+const ALLOWED_ATTRIBUTES = [
+  'id', 'class', 'style', 'title', 'lang', 'dir',
+  'href', 'target', 'rel', 'download',
+  'src', 'alt', 'width', 'height', 'loading',
+  'colspan', 'rowspan', 'scope', 'headers',
+  'open', 'datetime', 'cite'
+] as const;
+
+/**
+ * Basic HTML sanitization function using regex-based approach
+ * Removes potentially dangerous elements and attributes while preserving basic formatting
+ * This approach is more reliable in SSR environments and doesn't require DOM manipulation
+ * 
+ * @param html - The HTML string to sanitize
+ * @returns Sanitized HTML string safe for rendering
+ * 
+ * @example
+ * ```tsx
+ * const safeHtml = sanitizeHtml('<p>Hello <strong>world</strong>!</p>');
+ * // Returns: '<p>Hello <strong>world</strong>!</p>'
+ * 
+ * const dangerousHtml = sanitizeHtml('<script>alert("xss")</script><p>Safe content</p>');
+ * // Returns: '<p>Safe content</p>'
+ * ```
+ */
+export function sanitizeHtml(html: string): string {
+  if (!html || typeof html !== 'string') {
+    return '';
+  }
+
+  // For debugging, let's just return the HTML as-is for now
+  // This will help us see if the issue is with sanitization or rendering
+  console.log('🔍 sanitizeHtml input:', html);
+  
+  // Basic safety: just remove script tags and dangerous attributes
+  let sanitized = html
+    // Remove script tags (including self-closing and malformed)
+    .replace(/<script\b[^>]*>.*?<\/script>/gi, '')
+    .replace(/<script\b[^>]*\/>/gi, '')
+    // Remove iframe tags (including self-closing and malformed)
+    .replace(/<iframe\b[^>]*>.*?<\/iframe>/gi, '')
+    .replace(/<iframe\b[^>]*\/>/gi, '')
+    // Remove object tags (including self-closing and malformed)
+    .replace(/<object\b[^>]*>.*?<\/object>/gi, '')
+    .replace(/<object\b[^>]*\/>/gi, '')
+    // Remove embed tags (including self-closing)
+    .replace(/<embed\b[^>]*\/?>/gi, '')
+    // Remove form tags (including self-closing and malformed)
+    .replace(/<form\b[^>]*>.*?<\/form>/gi, '')
+    .replace(/<form\b[^>]*\/>/gi, '')
+    // Remove input tags (including self-closing)
+    .replace(/<input\b[^>]*\/?>/gi, '')
+    // Remove button tags (including self-closing and malformed)
+    .replace(/<button\b[^>]*>.*?<\/button>/gi, '')
+    .replace(/<button\b[^>]*\/>/gi, '')
+    // Remove event handlers from any remaining tags - correct pattern
+    .replace(/\s*on\w+\s*=\s*["'][^"']*["']/gi, '')
+    // Remove javascript: protocols - correct pattern
+    .replace(/javascript:[^"'\s>]*/gi, '')
+    // Remove data: protocols - correct pattern
+    .replace(/data:[^"'\s>]*/gi, '');
+
+  console.log('🔍 sanitizeHtml output:', sanitized);
+  return sanitized;
+}
+
+/**
+ * Validates if HTML content is safe for rendering
+ * 
+ * @param html - The HTML string to validate
+ * @returns Object with validation result and any warnings
+ * 
+ * @example
+ * ```tsx
+ * const validation = validateHtml('<p>Safe content</p>');
+ * console.log(validation.isValid); // true
+ * console.log(validation.warnings); // []
+ * ```
+ */
+export function validateHtml(html: string): { isValid: boolean; warnings: string[] } {
+  const warnings: string[] = [];
+  
+  if (!html || typeof html !== 'string') {
+    return { isValid: false, warnings: ['HTML content must be a non-empty string'] };
+  }
+
+  // Check for potentially dangerous patterns
+  const dangerousPatterns = [
+    { pattern: /<script\b[^>]*>.*?<\/script>/gi, message: 'Script tags are not allowed' },
+    { pattern: /<script\b[^>]*\/>/gi, message: 'Script tags are not allowed' },
+    { pattern: /<iframe\b[^>]*>.*?<\/iframe>/gi, message: 'Iframe tags are not allowed' },
+    { pattern: /<iframe\b[^>]*\/>/gi, message: 'Iframe tags are not allowed' },
+    { pattern: /<object\b[^>]*>.*?<\/object>/gi, message: 'Object tags are not allowed' },
+    { pattern: /<object\b[^>]*\/>/gi, message: 'Object tags are not allowed' },
+    { pattern: /<embed\b[^>]*\/?>/gi, message: 'Embed tags are not allowed' },
+    { pattern: /<form\b[^>]*>.*?<\/form>/gi, message: 'Form tags are not allowed' },
+    { pattern: /<form\b[^>]*\/>/gi, message: 'Form tags are not allowed' },
+    { pattern: /<input\b[^>]*\/?>/gi, message: 'Input tags are not allowed' },
+    { pattern: /<button\b[^>]*>.*?<\/button>/gi, message: 'Button tags are not allowed' },
+    { pattern: /<button\b[^>]*\/>/gi, message: 'Button tags are not allowed' },
+    { pattern: /on\w+\s*=/gi, message: 'Event handlers are not allowed' },
+    { pattern: /javascript:/gi, message: 'JavaScript protocols are not allowed' },
+    { pattern: /data:/gi, message: 'Data protocols are not allowed' }
+  ];
+
+  dangerousPatterns.forEach(({ pattern, message }) => {
+    if (pattern.test(html)) {
+      warnings.push(message);
+    }
+  });
+
+  return {
+    isValid: warnings.length === 0,
+    warnings
+  };
+}
+
+/**
+ * Safely renders HTML content with sanitization
+ * 
+ * @param html - The HTML string to render
+ * @param options - Rendering options
+ * @returns Object with sanitized HTML and validation info
+ * 
+ * @example
+ * ```tsx
+ * const result = renderSafeHtml('<p>Hello <strong>world</strong>!</p>');
+ * console.log(result.html); // Sanitized HTML
+ * console.log(result.isValid); // true
+ * ```
+ */
+export function renderSafeHtml(
+  html: string, 
+  options: { 
+    strict?: boolean; 
+    logWarnings?: boolean;
+  } = {}
+): { 
+  html: string; 
+  isValid: boolean; 
+  warnings: string[] 
+} {
+  const { strict = true, logWarnings = false } = options;
+  
+  const validation = validateHtml(html);
+  const sanitizedHtml = sanitizeHtml(html);
+  
+  if (logWarnings && validation.warnings.length > 0) {
+    console.warn('Dialog HTML content warnings:', validation.warnings);
+  }
+  
+  return {
+    html: sanitizedHtml,
+    isValid: validation.isValid,
+    warnings: validation.warnings
+  };
+}

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

@@ -15,7 +15,7 @@ import { renderWithProviders } from '../../__tests__/helpers/test-utils';
 
 // Mock the current year for consistent testing
 const mockCurrentYear = 2024;
-vi.mock('../../utils/cn', () => ({
+vi.mock('../../utils/core/cn', () => ({
   cn: (...classes: (string | undefined)[]) => classes.filter(Boolean).join(' ')
 }));
 

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

@@ -16,7 +16,7 @@ import { Form, FormField } from './index';
 import { renderWithProviders } from '../../__tests__/helpers/test-utils';
 
 // Mock the cn utility
-vi.mock('../../utils/cn', () => ({
+vi.mock('../../utils/core/cn', () => ({
   cn: (...classes: (string | undefined)[]) => classes.filter(Boolean).join(' ')
 }));
 

package/src/components/Form/FormErrorSummary.tsx

@@ -0,0 +1,113 @@
+
+/**
+ * @file FormErrorSummary Component
+ * @package @jmruthers/pace-core
+ * @module Components/Form
+ * @since 0.1.0
+ *
+ * A form error summary component that displays validation errors in a user-friendly format.
+ * Provides a centralized location for users to see all form errors at once.
+ *
+ * Features:
+ * - Displays all form errors in one place
+ * - Configurable error display format
+ * - Optional field name display
+ * - Accessible error presentation
+ * - Consistent styling with Alert component
+ * - Automatic error filtering
+ * - Responsive design
+ *
+ * @example
+ * ```tsx
+ * // Basic error summary
+ * <FormErrorSummary errors={formErrors} />
+ * 
+ * // With custom title
+ * <FormErrorSummary 
+ *   errors={formErrors}
+ *   title="Please correct the following issues:"
+ * />
+ * 
+ * // Show field names with errors
+ * <FormErrorSummary 
+ *   errors={formErrors}
+ *   showFieldNames={true}
+ * />
+ * 
+ * // In a form with React Hook Form
+ * const { formState: { errors } } = useForm();
+ * 
+ * <Form onSubmit={handleSubmit}>
+ *   <FormField name="email" label="Email" />
+ *   <FormField name="password" label="Password" />
+ *   <FormErrorSummary errors={errors} />
+ *   <Button type="submit">Submit</Button>
+ * </Form>
+ * ```
+ *
+ * @accessibility
+ * - Uses Alert component for consistent accessibility
+ * - Proper heading hierarchy with h3
+ * - List structure for error items
+ * - Screen reader friendly error announcements
+ * - High contrast support via Alert component
+ *
+ * @dependencies
+ * - Alert component for consistent styling
+ * - React 18+ - Component framework
+ * - Tailwind CSS - Styling
+ */
+
+import { Alert } from '../Alert';
+
+export interface FormErrorSummaryProps {
+  /** Form validation errors object */
+  errors?: Record<string, any>;
+  /** Title displayed above the error list */
+  title?: string;
+  /** Whether to show field names alongside error messages */
+  showFieldNames?: boolean;
+}
+
+/**
+ * FormErrorSummary component for displaying form validation errors
+ * 
+ * This component provides a user-friendly way to display all form errors
+ * in one centralized location, improving the user experience by making
+ * it clear what needs to be fixed.
+ * 
+ * @param props - Component configuration
+ * @param props.errors - Form validation errors object
+ * @param props.title - Title displayed above the error list
+ * @param props.showFieldNames - Whether to show field names with errors
+ * @returns JSX.Element - The rendered error summary or null if no errors
+ */
+export function FormErrorSummary({ 
+  errors = {}, 
+  title = "Please fix the following errors:",
+  showFieldNames = false 
+}: FormErrorSummaryProps) {
+  const errorEntries = Object.entries(errors).filter(([, value]) => Boolean(value));
+
+  if (errorEntries.length === 0) {
+    return null;
+  }
+
+  return (
+    <Alert variant="destructive" className="mb-4">
+      <div>
+        <h3>{title}</h3>
+        <ul className="list-disc list-inside space-y-1">
+          {errorEntries.map(([field, error], index) => {
+            const message = typeof error === 'object' && error.message ? error.message : String(error);
+            return (
+              <li key={index} className="text-sm">
+                {showFieldNames ? `${field}: ${message}` : message}
+              </li>
+            );
+          })}
+        </ul>
+      </div>
+    </Alert>
+  );
+}

package/src/components/Form/FormFieldset.tsx

@@ -0,0 +1,127 @@
+/**
+ * @file FormFieldset Component
+ * @package @jmruthers/pace-core
+ * @module Components/Form
+ * @since 0.1.0
+ *
+ * A form fieldset component that groups related form fields together with a legend
+ * and optional description. Provides semantic structure and accessibility for form sections.
+ *
+ * Features:
+ * - Semantic fieldset grouping for related form fields
+ * - Accessible legend with required indicator
+ * - Optional description text with proper ARIA association
+ * - Consistent styling with design system
+ * - Forwarded ref support
+ * - Customizable styling via className
+ * - Required field indication
+ * - Responsive design
+ *
+ * @example
+ * ```tsx
+ * // Basic fieldset
+ * <FormFieldset legend="Personal Information">
+ *   <FormField name="firstName" label="First Name" />
+ *   <FormField name="lastName" label="Last Name" />
+ *   <FormField name="email" label="Email" />
+ * </FormFieldset>
+ * 
+ * // Fieldset with description
+ * <FormFieldset 
+ *   legend="Contact Details" 
+ *   description="We'll use this information to contact you about your order"
+ * >
+ *   <FormField name="phone" label="Phone Number" />
+ *   <FormField name="address" label="Address" />
+ * </FormFieldset>
+ * 
+ * // Required fieldset
+ * <FormFieldset 
+ *   legend="Account Settings" 
+ *   required={true}
+ *   description="These settings are required for account creation"
+ * >
+ *   <FormField name="username" label="Username" required />
+ *   <FormField name="password" label="Password" type="password" required />
+ * </FormFieldset>
+ * 
+ * // With custom styling
+ * <FormFieldset 
+ *   legend="Preferences"
+ *   className="bg-sec-50 border-sec-200"
+ * >
+ *   <FormField name="newsletter" label="Subscribe to newsletter" type="checkbox" />
+ *   <FormField name="notifications" label="Enable notifications" type="checkbox" />
+ * </FormFieldset>
+ * ```
+ *
+ * @accessibility
+ * - Proper semantic HTML with fieldset and legend
+ * - ARIA describedby association for descriptions
+ * - Required field indication with asterisk
+ * - Screen reader friendly structure
+ * - Keyboard navigation support
+ * - WCAG 2.1 AA compliant
+ *
+ * @dependencies
+ * - React 18+ - Component framework and hooks
+ * - Tailwind CSS - Styling
+ * - cn utility - Class name merging
+ */
+
+import React from 'react';
+import { cn } from '../../utils/cn';
+
+export interface FormFieldsetProps extends React.FieldsetHTMLAttributes<HTMLFieldSetElement> {
+  /** The legend text for the fieldset */
+  legend: string;
+  /** Optional description text below the legend */
+  description?: string;
+  /** Whether the fieldset contains required fields */
+  required?: boolean;
+  /** Form fields to group within the fieldset */
+  children: React.ReactNode;
+}
+
+/**
+ * FormFieldset component for grouping related form fields
+ * 
+ * This component provides semantic grouping for form fields with proper
+ * accessibility support and consistent styling. Use it to organize
+ * related form inputs into logical sections.
+ * 
+ * @param props - Component configuration
+ * @param props.legend - The legend text for the fieldset
+ * @param props.description - Optional description text
+ * @param props.required - Whether the fieldset contains required fields
+ * @param props.children - Form fields to group
+ * @param ref - Forwarded ref to the fieldset element
+ * @returns JSX.Element - The rendered fieldset with legend and fields
+ */
+export const FormFieldset = React.forwardRef<HTMLFieldSetElement, FormFieldsetProps>(
+  ({ legend, description, required, className, children, ...props }, ref) => {
+    const descriptionId = React.useId();
+    
+    return (
+      <fieldset
+        ref={ref}
+        className={cn("space-y-4 border border-input rounded-lg p-4", className)}
+        aria-describedby={description ? descriptionId : undefined}
+        {...props}
+      >
+        <legend className="px-2">
+          {legend}
+          {required && <span className="text-destructive ml-1">*</span>}
+        </legend>
+        {description && (
+          <p id={descriptionId} className="text-muted-foreground">
+            {description}
+          </p>
+        )}
+        {children}
+      </fieldset>
+    );
+  }
+);
+
+FormFieldset.displayName = "FormFieldset";

package/src/components/Form/FormLiveRegion.tsx

@@ -0,0 +1,198 @@
+/**
+ * @file FormLiveRegion Component
+ * @package @jmruthers/pace-core
+ * @module Components/Form
+ * @since 0.1.0
+ *
+ * An accessible live region component for form validation announcements.
+ * Provides real-time feedback to screen readers about form validation states
+ * and error messages, improving accessibility for users with assistive technologies.
+ *
+ * Features:
+ * - Real-time form validation announcements
+ * - Configurable politeness levels (polite/assertive)
+ * - Customizable delay timing
+ * - Field-level and form-level announcements
+ * - Success message customization
+ * - Automatic error counting and field identification
+ * - Accessibility compliant with ARIA live regions
+ * - Integration with React Hook Form
+ *
+ * @example
+ * ```tsx
+ * // Basic live region
+ * const { control, formState } = useForm();
+ * 
+ * <Form onSubmit={handleSubmit}>
+ *   <FormField name="email" label="Email" />
+ *   <FormField name="password" label="Password" />
+ *   <FormLiveRegion form={{ control, formState }} />
+ *   <Button type="submit">Submit</Button>
+ * </Form>
+ * 
+ * // With custom configuration
+ * <FormLiveRegion
+ *   form={{ control, formState }}
+ *   politeness="assertive"
+ *   delay={1000}
+ *   successMessage="Your form was submitted successfully!"
+ *   enableFieldAnnouncements={true}
+ * />
+ * 
+ * // In a complex form
+ * function ComplexForm() {
+ *   const methods = useForm({
+ *     defaultValues: { name: '', email: '', message: '' }
+ *   });
+ *   
+ *   return (
+ *     <FormProvider {...methods}>
+ *       <form onSubmit={methods.handleSubmit(onSubmit)}>
+ *         <FormField name="name" label="Name" />
+ *         <FormField name="email" label="Email" />
+ *         <FormField name="message" label="Message" />
+ *         <FormLiveRegion 
+ *           form={methods}
+ *           politeness="polite"
+ *           delay={300}
+ *         />
+ *         <Button type="submit">Send Message</Button>
+ *       </form>
+ *     </FormProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @accessibility
+ * - ARIA live region for screen reader announcements
+ * - Configurable politeness levels for different message types
+ * - Automatic error counting and field identification
+ * - Non-intrusive validation feedback
+ * - WCAG 2.1 AA compliant
+ * - Screen reader friendly error announcements
+ *
+ * @dependencies
+ * - react-hook-form - Form state management
+ * - React 18+ - Hooks and effects
+ * - Tailwind CSS - Styling
+ */
+
+import React, { useEffect, useState } from 'react';
+import { UseFormReturn, FieldValues } from 'react-hook-form';
+import { cn } from '../../utils/cn';
+
+/**
+ * Props for the FormLiveRegion component
+ */
+export interface FormLiveRegionProps<T extends FieldValues> {
+  /** React Hook Form instance */
+  form: UseFormReturn<T>;
+  /** ARIA live region politeness level */
+  politeness?: 'polite' | 'assertive';
+  /** Delay before announcing messages (in ms) */
+  delay?: number;
+  /** Custom success message */
+  successMessage?: string;
+  /** Custom class name */
+  className?: string;
+  /** Enable field-level validation announcements */
+  enableFieldAnnouncements?: boolean;
+}
+
+/**
+ * FormLiveRegion component for accessible form validation announcements
+ */
+export function FormLiveRegion<T extends FieldValues>({
+  form,
+  politeness = 'polite',
+  delay = 500,
+  successMessage = 'Form submitted successfully',
+  className,
+  enableFieldAnnouncements = true
+}: FormLiveRegionProps<T>): React.ReactElement {
+  const [message, setMessage] = useState<string>('');
+  const { formState } = form;
+
+  // Handle form-level announcements
+  useEffect(() => {
+    let timeoutId: NodeJS.Timeout;
+
+    if (formState.isSubmitting) {
+      setMessage('Submitting form...');
+    } else if (formState.isSubmitSuccessful) {
+      timeoutId = setTimeout(() => {
+        setMessage(successMessage);
+      }, delay);
+    } else if (formState.errors && Object.keys(formState.errors).length > 0) {
+      const errorCount = Object.keys(formState.errors).length;
+      const errorFields = Object.keys(formState.errors).join(', ');
+      setMessage(`Form has ${errorCount} error${errorCount === 1 ? '' : 's'} in: ${errorFields}`);
+    } else if (formState.isValid && formState.isDirty) {
+      setMessage('Form is valid');
+    } else {
+      setMessage('');
+    }
+
+    return () => {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    };
+  }, [formState, delay, successMessage]);
+
+  // Handle field-level announcements
+  useEffect(() => {
+    if (!enableFieldAnnouncements) return;
+
+    let timeoutId: NodeJS.Timeout;
+    
+    const fieldErrors = formState.errors;
+    const touchedFields = formState.touchedFields;
+    
+    // Find newly touched fields with errors
+    const newErrors = Object.keys(fieldErrors).filter(field => {
+      // Type-safe access to touchedFields
+      const touchedField = touchedFields as Record<string, boolean>;
+      return touchedField[field] && fieldErrors[field as keyof typeof fieldErrors];
+    });
+
+    if (newErrors.length > 0) {
+      timeoutId = setTimeout(() => {
+        const errorField = newErrors[0];
+        const errorData = fieldErrors[errorField as keyof typeof fieldErrors];
+        const errorMessage = errorData?.message;
+        if (errorMessage) {
+          setMessage(`${errorField}: ${errorMessage}`);
+        }
+      }, delay);
+    }
+
+    return () => {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    };
+  }, [formState.errors, formState.touchedFields, enableFieldAnnouncements, delay]);
+
+  if (!message) {
+    return <></>;
+  }
+
+  return (
+    <div
+      role="status"
+      aria-live={politeness}
+      aria-atomic="true"
+      className={cn('sr-only', className)}
+      style={{
+        position: 'absolute',
+        left: '-10000px',
+        width: '1px',
+        height: '1px',
+        overflow: 'hidden'
+      }}
+    >
+      {message}
+    </div>
+  );
+}

package/src/components/LoginForm/LoginForm.test.tsx

@@ -100,7 +100,7 @@ vi.mock('../Alert/Alert', () => ({
 }));
 
 // Mock the cn utility
-vi.mock('../../utils/cn', () => ({
+vi.mock('../../utils/core/cn', () => ({
   cn: (...classes: any[]) => classes.filter(Boolean).join(' '),
 }));