@pixelated-tech/components 3.2.13 → 3.3.0

package/README.COMPONENTS.md

@@ -11,6 +11,7 @@ This guide provides detailed API documentation and usage examples for all Pixela
 - [Modal](#modal)
 - [SidePanel](#sidepanel)
 - [SmartImage](#smartimage)
+- [Tab](#tab)
 - [Table](#table)
 
 ### CMS Integration
@@ -34,6 +35,7 @@ This guide provides detailed API documentation and usage examples for all Pixela
 - [ComponentPropertiesForm](#componentpropertiesform)
 - [ComponentSelector](#componentselector)
 - [ComponentTree](#componenttree)
+- [ConfigBuilder](#configbuilder)
 - [PageBuilderUI](#pagebuilderui)
 - [PageEngine](#pageengine)
 - [SaveLoadSection](#saveloadsection)
@@ -44,6 +46,7 @@ This guide provides detailed API documentation and usage examples for all Pixela
 - [GoogleMap](#googlemap)
 - [GoogleSearch](#googlesearch)
 - [JSON-LD Schemas](#json-ld-schemas)
+- [Manifest](#manifest)
 - [MetadataComponents](#metadatacomponents)
 
 ### Shopping Cart
@@ -553,7 +556,7 @@ const reviews = [
 
 ### Forms
 
-Dynamic form builder that generates forms from JSON configuration.
+Dynamic form builder that generates forms from JSON configuration with comprehensive validation and event handling.
 
 #### FormEngine
 
@@ -565,21 +568,39 @@ import { FormEngine } from '@pixelated-tech/components';
 const formConfig = {
   fields: [
     {
-      type: 'text',
+      component: 'FormInput',
       props: {
+        type: 'text',
+        id: 'email',
         name: 'email',
         label: 'Email Address',
         placeholder: 'Enter your email',
-        required: true
+        required: 'required',
+        validate: 'email'
       }
     },
     {
-      type: 'textarea',
+      component: 'FormTextarea',
       props: {
+        id: 'message',
         name: 'message',
         label: 'Message',
         placeholder: 'Enter your message',
-        rows: 4
+        rows: '4',
+        required: 'required'
+      }
+    },
+    {
+      component: 'FormSelect',
+      props: {
+        id: 'category',
+        name: 'category',
+        label: 'Category',
+        options: [
+          { text: 'General', value: 'general' },
+          { text: 'Support', value: 'support' },
+          { text: 'Sales', value: 'sales' }
+        ]
       }
     }
   ]
@@ -594,36 +615,171 @@ const formConfig = {
 
 #### Form Components
 
-Individual form field components for custom form building.
+Individual form field components with unified event handling and validation.
+
+##### FormInput
+Text input field with validation and accessibility features.
 
 ```tsx
-import * as FC from '@pixelated-tech/components';
+import { FormInput } from '@pixelated-tech/components';
+
+<FormInput
+  type="email"
+  id="email"
+  name="email"
+  label="Email Address"
+  placeholder="Enter your email"
+  required="required"
+  validate="email"
+  display="vertical"
+/>
+```
 
-function CustomForm() {
-  return (
-    <form>
-      <FC.TextInput
-        name="username"
-        label="Username"
-        required={true}
-        placeholder="Enter username"
-      />
-      <FC.EmailInput
-        name="email"
-        label="Email"
-        required={true}
-      />
-      <FC.TextArea
-        name="bio"
-        label="Bio"
-        rows={4}
-        placeholder="Tell us about yourself"
-      />
-    </form>
-  );
-}
+**Props:**
+- `type`: Input type (text, email, password, etc.)
+- `id`: Unique identifier
+- `name`: Form field name
+- `label`: Display label
+- `placeholder`: Input placeholder text
+- `required`: Makes field required
+- `validate`: Validation rule name
+- `display`: Layout mode (vertical/horizontal)
+
+##### FormTextarea
+Multi-line text input with validation.
+
+```tsx
+import { FormTextarea } from '@pixelated-tech/components';
+
+<FormTextarea
+  id="description"
+  name="description"
+  label="Description"
+  placeholder="Enter description"
+  rows="4"
+  required="required"
+  display="vertical"
+/>
 ```
 
+##### FormSelect
+Dropdown selection with option validation.
+
+```tsx
+import { FormSelect } from '@pixelated-tech/components';
+
+<FormSelect
+  id="category"
+  name="category"
+  label="Category"
+  options={[
+    { text: 'Option 1', value: 'opt1' },
+    { text: 'Option 2', value: 'opt2' }
+  ]}
+  required="required"
+/>
+```
+
+##### FormRadio
+Radio button group with validation.
+
+```tsx
+import { FormRadio } from '@pixelated-tech/components';
+
+<FormRadio
+  id="choice"
+  name="choice"
+  label="Choose an option"
+  options={[
+    { text: 'Option A', value: 'a' },
+    { text: 'Option B', value: 'b' }
+  ]}
+  required="required"
+/>
+```
+
+##### FormCheckbox
+Checkbox group with validation.
+
+```tsx
+import { FormCheckbox } from '@pixelated-tech/components';
+
+<FormCheckbox
+  id="preferences"
+  name="preferences"
+  label="Preferences"
+  options={[
+    { text: 'Email updates', value: 'email' },
+    { text: 'SMS updates', value: 'sms' }
+  ]}
+/>
+```
+
+##### FormButton
+Action button for form submission.
+
+```tsx
+import { FormButton } from '@pixelated-tech/components';
+
+<FormButton
+  type="submit"
+  id="submit-btn"
+  text="Submit Form"
+  onClick={handleSubmit}
+/>
+```
+
+##### FormTooltip
+Unified tooltip and validation message component with mouseover behavior and conditional styling.
+
+```tsx
+import { FormTooltip } from '@pixelated-tech/components';
+
+// Tooltip mode - displays information with black ⓘ icon
+<FormTooltip
+  mode="tooltip"
+  text={['This field is required', 'Please enter a valid email address']}
+/>
+
+// Validation mode - displays errors with red ❌ icon
+<FormTooltip
+  mode="validate"
+  text={['Email format is invalid', 'Please check your input']}
+/>
+```
+
+**Props:**
+- `mode`: Display mode ('tooltip' for info, 'validate' for errors)
+- `text`: Array of strings to display (always use array format)
+
+**Features:**
+- **Conditional Icons**: ⓘ (black) for tooltips, ❌ (red) for validation errors
+- **Mouseover Behavior**: Shows/hides content on hover for both modes
+- **Unified Styling**: Consistent appearance with mode-based color variations
+- **Array-Based Text**: Always accepts text as string array for consistency
+
+#### Form Validation
+
+Built-in validation rules available via the `validate` prop:
+
+- `email`: Email format validation
+- `url`: URL format validation
+- `phone`: Phone number format
+- `zipcode`: US zip code validation
+- `required`: Required field validation
+- Custom validation functions can be added to `formvalidations.tsx`
+
+#### Recent Improvements
+
+**Version 3.2.14+** includes major refactoring for better performance and maintainability:
+
+- **FormTooltip Unification**: Merged FormTooltip and FormValidate into single component with mode-based rendering
+- **Unified Event Handling**: All form components now use consistent `onChange` and `onInput` handlers for better test compatibility
+- **Performance Optimization**: Replaced inefficient `JSON.parse/stringify` with direct object destructuring
+- **Code Deduplication**: Custom `useFormComponent` hook eliminates repetitive validation logic
+- **Circular Reference Prevention**: Fixed memory leaks in option generation for radio/checkbox components
+- **Enhanced Test Coverage**: 2,244 tests passing across 67 test files with comprehensive form component coverage
+
 ### Menu
 
 Navigation components with multiple interaction patterns.
@@ -690,6 +846,29 @@ const menuItems = [
 <MenuExpando menuItems={menuItems} />
 ```
 
+### Tab
+
+Configurable tab component with multiple orientations and content areas.
+
+```tsx
+import { Tab } from '@pixelated-tech/components';
+
+const tabs = [
+  { id: 'tab1', label: 'Tab 1', content: <div>Content for Tab 1</div> },
+  { id: 'tab2', label: 'Tab 2', content: <div>Content for Tab 2</div> },
+  { id: 'tab3', label: 'Tab 3', content: <div>Content for Tab 3</div> },
+];
+
+<Tab tabs={tabs} orientation="top" defaultActiveTab="tab1" />
+```
+
+#### Props
+
+- `tabs`: Array of tab objects with `id`, `label`, and `content`
+- `orientation`: 'top' | 'bottom' | 'left' | 'right' (default: 'top')
+- `defaultActiveTab`: ID of the initially active tab
+- `onTabChange`: Callback function called when tab changes
+
 ### Tables
 
 Data display component with sorting and image support.
@@ -873,6 +1052,87 @@ import { SaveLoadSection } from '@pixelated-tech/components';
 | `onLoad` | `function` | - | Load handler |
 | `onNew` | `function` | - | New page handler |
 
+### ConfigBuilder
+
+Tabbed interface for managing site metadata and routes configuration.
+
+```tsx
+import { ConfigBuilder } from '@pixelated-tech/components';
+
+<ConfigBuilder
+  initialConfig={{
+    siteInfo: { name: 'My Site', description: 'Site description' },
+    routes: [
+      { path: '/home', component: 'Home', title: 'Home Page' }
+    ]
+  }}
+  onSave={(config) => console.log('Config saved:', config)}
+/>
+```
+
+#### Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `initialConfig` | `SiteConfig` | - | Initial site configuration |
+| `onSave` | `function` | - | Configuration save handler |
+
+#### SiteConfig Type
+```tsx
+interface SiteConfig {
+  siteInfo: {
+    name: string;
+    author: string;
+    description: string;
+    url: string;
+    email: string;
+    favicon: string;
+    favicon_sizes: string;
+    favicon_type: string;
+    theme_color: string;
+    background_color: string;
+    default_locale: string;
+    display: string;
+    image?: string;
+    image_height?: string;
+    image_width?: string;
+    telephone?: string;
+    address?: {
+      streetAddress: string;
+      addressLocality: string;
+      addressRegion: string;
+      postalCode: string;
+      addressCountry: string;
+    };
+    priceRange?: string;
+    sameAs?: string[];
+    keywords?: string;
+  };
+  routes: Array<{
+    path: string;
+    component: string;
+    title?: string;
+    description?: string;
+  }>;
+}
+```
+
+#### Features
+- **Tabbed Interface**: Organized into "Site Info" and "Routes" tabs
+- **Comprehensive Site Info Management**: Edit all standard site metadata fields including PWA settings, contact info, and address
+- **Route Management**: Add, edit, and remove page routes with component mapping
+- **Real-time Preview**: JSON preview of current configuration
+- **Save Functionality**: Callback-based configuration persistence with form validation enforcement
+- **Form Validation**: Required field validation for essential site information with visual feedback
+
+#### Validation Behavior
+
+The "Save Config" button enforces form validation before allowing configuration saves:
+
+- **Required Fields**: Site name, author, description, URL, and email are mandatory
+- **Visual Feedback**: Invalid fields show validation errors with ❌ indicators
+- **Save Prevention**: Save action is blocked until all required validations pass
+- **Real-time Validation**: Form validates as you type with immediate feedback
+
 ---
 
 ## SEO & Schema
@@ -881,11 +1141,16 @@ import { SaveLoadSection } from '@pixelated-tech/components';
 
 Structured data components for SEO.
 
+**Configuration**: The LocalBusiness and Website schema components can use `siteInfo` data from the routes JSON file as fallback values when props are not explicitly provided. This allows for centralized site-wide configuration of business/website information.
+
 #### LocalBusiness
 
+Generates LocalBusiness JSON-LD structured data. When props are not provided, falls back to `siteInfo` configuration from routes JSON.
+
 ```tsx
 import { LocalBusinessSchema } from '@pixelated-tech/components';
 
+// With explicit props
 <LocalBusinessSchema
   name="My Business"
   address={{
@@ -896,6 +1161,19 @@ import { LocalBusinessSchema } from '@pixelated-tech/components';
   }}
   telephone="(555) 123-4567"
 />
+
+// Or with siteinfo object (recommended)
+<LocalBusinessSchema
+  siteInfo={siteInfoData}
+  streetAddress="123 Main St"
+  addressLocality="City"
+  addressRegion="State"
+  postalCode="12345"
+/>
+
+// Or with minimal props (uses siteInfo fallbacks)
+<LocalBusinessSchema />
+```
 ```
 
 #### Recipe
@@ -941,9 +1219,12 @@ import { ServicesSchema } from '@pixelated-tech/components';
 
 #### Website
 
+Generates Website JSON-LD structured data. When props are not provided, falls back to `siteInfo` configuration from routes JSON.
+
 ```tsx
 import { WebsiteSchema } from '@pixelated-tech/components';
 
+// With explicit props
 <WebsiteSchema
   name="My Website"
   url="https://example.com"
@@ -953,6 +1234,22 @@ import { WebsiteSchema } from '@pixelated-tech/components';
     logo: "https://example.com/logo.png"
   }}
 />
+
+// Or with siteinfo object (recommended)
+<WebsiteSchema
+  siteInfo={siteInfoData}
+  potentialAction={{
+    '@type': 'SearchAction',
+    target: {
+      '@type': 'EntryPoint',
+      urlTemplate: 'https://example.com/search?q={search_term}'
+    }
+  }}
+/>
+
+// Or with minimal props (uses siteInfo fallbacks)
+<WebsiteSchema />
+```
 ```
 
 #### BlogPosting
@@ -1057,6 +1354,52 @@ import { GoogleSearch } from '@pixelated-tech/components';
 | `apiKey` | `string` | - | Google API key |
 | `placeholder` | `string` | `'Search...'` | Search input placeholder |
 
+### Manifest
+
+Generates a complete PWA manifest from siteinfo configuration. This component centralizes PWA manifest generation and ensures consistency across sites.
+
+```tsx
+import { Manifest } from '@pixelated-tech/components';
+
+// Basic usage with siteinfo
+export default function manifest() {
+  return Manifest({ siteInfo: myRoutes.siteInfo });
+}
+
+// With custom properties for site-specific overrides
+export default function manifest() {
+  return Manifest({ 
+    siteInfo: myRoutes.siteInfo,
+    customProperties: {
+      orientation: 'portrait',
+      categories: ['business', 'productivity'],
+      lang: 'en-US'
+    }
+  });
+}
+```
+
+#### Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `siteInfo` | `SiteInfo` | - | Site configuration object from routes.json |
+| `customProperties` | `Partial<MetadataRoute.Manifest>` | `{}` | Optional custom manifest properties to override defaults |
+
+#### Generated Properties
+
+The component automatically generates these manifest properties from `siteInfo`:
+
+- `name` & `short_name`: From `siteInfo.name`
+- `description`: From `siteInfo.description`
+- `theme_color`: From `siteInfo.theme_color`
+- `background_color`: From `siteInfo.background_color`
+- `display`: From `siteInfo.display`
+- `homepage_url`: From `siteInfo.url`
+- `developer`: Object with `name` and `url` from siteInfo
+- `icons`: Array with favicon configuration
+- `author`: From `siteInfo.author` (non-standard property)
+- `default_locale`: From `siteInfo.default_locale`
+
 ### MetadataComponents
 
 Dynamic meta tag injection for SEO.
@@ -1312,7 +1655,19 @@ import { NerdJoke } from '@pixelated-tech/components';
 
 ### PixelatedClientConfigProvider Setup
 
-For components that use external services, wrap your app with the configuration provider:
+The PixelatedClientConfigProvider enables components to access centralized configuration data. Configuration can be loaded from environment variables or a `routes.json` file in your project.
+
+**Config Consumers:**
+- **LocalBusinessSchema & WebsiteSchema**: Use `siteInfo` for fallback business/website data
+- **CloudinaryImage & SmartImage**: Use `cloudinary` for image optimization settings
+- **WordPress**: Use `wordpress` for API connections
+- **ContentfulItems**: Use `contentful` for CMS integration
+- **eBay**: Use `ebay` for store integration
+- **Flickr**: Use `flickr` for photo gallery integration
+- **GoogleAnalytics**: Use `googleAnalytics` for tracking
+- **HubSpot**: Use `hubspot` for CRM integration
+- **PayPal**: Use `paypal` for payment processing
+- **Proxy**: Use `proxy` for API proxy settings
 
 ```tsx
 // app/layout.tsx (Next.js 13+ App Router)
@@ -1327,15 +1682,63 @@ export default function RootLayout({
     <html lang="en">
       <body>
         <PixelatedClientConfigProvider config={{
+          // Site-wide business/website information (used by schema components)
+          siteInfo: {
+            name: 'Your Business Name',
+            description: 'Your business description',
+            url: 'https://yourwebsite.com',
+            email: 'contact@yourwebsite.com',
+            telephone: '(555) 123-4567',
+            address: {
+              streetAddress: '123 Main St',
+              addressLocality: 'City',
+              addressRegion: 'State',
+              postalCode: '12345',
+              addressCountry: 'United States'
+            },
+            openingHours: 'Mo-Fr 09:00-18:00'
+          },
+          // Image optimization
           cloudinary: {
             product_env: 'production',
             baseUrl: 'https://res.cloudinary.com/your-account',
             transforms: 'f_auto,q_auto,w_auto'
           },
+          // CMS integrations
           wordpress: {
             site: 'your-blog.wordpress.com'
           },
-          // Add other service configurations as needed
+          contentful: {
+            spaceId: 'your-space-id',
+            accessToken: 'your-access-token',
+            environment: 'master'
+          },
+          // E-commerce
+          ebay: {
+            appId: 'your-app-id',
+            globalId: 'EBAY-US'
+          },
+          paypal: {
+            sandboxPayPalApiKey: 'your-sandbox-key',
+            payPalApiKey: 'your-production-key'
+          },
+          // Analytics & CRM
+          googleAnalytics: {
+            id: 'GA-XXXXXXXXX'
+          },
+          hubspot: {
+            portalId: 'your-portal-id',
+            formId: 'your-form-id'
+          },
+          // Media services
+          flickr: {
+            api_key: 'your-flickr-api-key',
+            user_id: 'your-user-id'
+          },
+          // API proxy
+          proxy: {
+            proxyURL: 'https://proxy.pixelated.tech/prod/proxy?url='
+          }
         }}>
           {children}
         </PixelatedClientConfigProvider>
@@ -1345,52 +1748,6 @@ export default function RootLayout({
 }
 ```
 
-### Cloudinary Configuration
-
-```tsx
-const cloudinaryConfig = {
-  product_env: 'production',           // Environment identifier
-  baseUrl: 'https://res.cloudinary.com/your-account',  // Your Cloudinary URL
-  transforms: 'f_auto,q_auto,w_auto'   // Default transformations
-};
-```
-
-### WordPress Configuration
-
-```tsx
-const wordpressConfig = {
-  site: 'your-blog.wordpress.com',     // WordPress site URL
-  apiVersion: '1.1'                    // API version (optional)
-};
-```
-
-### Contentful Configuration
-
-```tsx
-const contentfulConfig = {
-  spaceId: 'your-space-id',            // Contentful space ID
-  accessToken: 'your-access-token',    // Contentful access token
-  environment: 'master'                // Contentful environment
-};
-```
-
-### Other Service Configurations
-
-```tsx
-const config = {
-  calendly: {
-    username: 'your-calendly-username'
-  },
-  hubspot: {
-    portalId: 'your-portal-id',
-    formId: 'your-form-id'
-  },
-  instagram: {
-    accessToken: 'your-access-token'
-  }
-};
-```
-
 ---
 
 ## TypeScript Support