@pixelated-tech/components 3.2.14 → 3.3.1

package/README.COMPONENTS.md

@@ -2,15 +2,29 @@
 
 This guide provides detailed API documentation and usage examples for all Pixelated Components.
 
-## 📋 Table of Contents
+## � Reference Implementation
+
+For a complete working example of Pixelated Components in action, check out the [pixelated-admin](https://github.com/brianwhaley/pixelated-admin) project. This admin interface demonstrates real-world usage of all components with:
+
+- **Component Integration**: Live examples of component combinations
+- **Configuration Management**: Dynamic site configuration with ConfigBuilder
+- **Page Building**: Visual page construction workflows
+- **Authentication**: Secure admin access patterns
+- **Production Setup**: HTTPS, optimization, and deployment configurations
+
+## �📋 Table of Contents
 
 ### General Components
 - [Accordion](#accordion)
 - [Callout](#callout)
+- [CSS](#css)
 - [Loading](#loading)
+- [MicroInteractions](#microinteractions)
 - [Modal](#modal)
+- [Semantic](#semantic)
 - [SidePanel](#sidepanel)
 - [SmartImage](#smartimage)
+- [Tab](#tab)
 - [Table](#table)
 
 ### CMS Integration
@@ -34,6 +48,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)
@@ -310,6 +325,76 @@ import { SmartImage } from '@pixelated-tech/components';
 | `width` | `number` | - | Image width |
 | `height` | `number` | - | Image height |
 
+### CSS
+
+Utility functions for CSS optimization and loading.
+
+```tsx
+import { deferAllCSS, preloadAllCSS } from '@pixelated-tech/components';
+
+// Defer CSS loading for better performance
+deferAllCSS();
+
+// Preload all CSS files
+preloadAllCSS();
+```
+
+#### Functions
+- **`deferAllCSS()`**: Defers loading of all CSS stylesheets for improved page load performance
+- **`preloadAllCSS()`**: Preloads all CSS files with high priority
+
+### MicroInteractions
+
+Component for adding subtle CSS animations and interactions to page elements.
+
+```tsx
+import { MicroInteractions } from '@pixelated-tech/components';
+
+<MicroInteractions
+  buttonring={true}
+  cartpulse={true}
+  formglow={true}
+  imgscale={true}
+  scrollfadeElements=".fade-on-scroll"
+/>
+```
+
+#### Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `buttonring` | `boolean` | - | Add ring animation to buttons |
+| `cartpulse` | `boolean` | - | Pulse animation for cart elements |
+| `formglow` | `boolean` | - | Glow effect for form inputs |
+| `grayscalehover` | `boolean` | - | Grayscale to color transition on hover |
+| `imgscale` | `boolean` | - | Scale animation for images |
+| `imgtwist` | `boolean` | - | Twist animation for images |
+| `imghue` | `boolean` | - | Hue rotation for images |
+| `simplemenubutton` | `boolean` | - | Animation for simple menu buttons |
+| `scrollfadeElements` | `string` | - | CSS selector for elements to fade on scroll |
+
+### Semantic
+
+Semantic HTML layout components for structured content.
+
+```tsx
+import { PageSection, PageTitleHeader, GridContainer } from '@pixelated-tech/components';
+
+<PageSection layoutType="grid" autoFlow="row">
+  <PageTitleHeader title="Welcome" />
+  <GridContainer columns={3} gap="1rem">
+    <div>Content 1</div>
+    <div>Content 2</div>
+    <div>Content 3</div>
+  </GridContainer>
+</PageSection>
+```
+
+#### Components
+- **`PageSection`**: Semantic section with configurable layout
+- **`PageTitleHeader`**: H1 title with optional link
+- **`GridContainer`**: CSS Grid container with responsive columns
+- **`FlexContainer`**: Flexbox container with alignment options
+
 ---
 
 ## CMS Integration
@@ -554,7 +639,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
 
@@ -566,21 +651,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' }
+        ]
       }
     }
   ]
@@ -595,36 +698,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.
@@ -691,6 +929,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.
@@ -874,6 +1135,234 @@ 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;
+  }>;
+  visualdesign?: {
+    'primary-color': string;
+    'secondary-color': string;
+    'accent1-color': string;
+    'accent2-color': string;
+    'bg-color': string;
+    'text-color': string;
+    'header-font-primary': string;
+    'header-font-fallback': string;
+    'header-font-generic': string;
+    'body-font-primary': string;
+    'body-font-fallback': string;
+    'body-font-generic': string;
+    'font-size1-min': string;
+    'font-size1-max': string;
+    'font-size2-min': string;
+    'font-size2-max': string;
+    'font-size3-min': string;
+    'font-size3-max': string;
+    'font-size4-min': string;
+    'font-size4-max': string;
+    'font-size5-min': string;
+    'font-size5-max': string;
+    'font-size6-min': string;
+    'font-size6-max': string;
+    'font-min-screen': string;
+    'font-max-screen': string;
+  };
+}
+```
+
+#### Features
+- **Tabbed Interface**: Organized into "Site Info", "Routes", and "Visual Design" 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
+- **Visual Design Configuration**: Manage design tokens like colors, fonts, and spacing through a form-based interface
+- **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
+
+#### Visual Design Tab
+
+The Visual Design tab provides a form-based interface for configuring visual design tokens. These tokens are stored in the `visualdesign` object of the site configuration and can be used to maintain consistent theming across your application.
+
+**Supported Design Tokens:**
+- **Colors**: Primary, secondary, accent, text, and background colors
+- **Typography**: Header and body fonts with primary Google Fonts, web-safe fallbacks, and generic family fallbacks
+- **Layout**: Border radius, box shadows, transition durations
+
+**Usage in Components:**
+```tsx
+// Access visual design tokens from config
+const config = useConfig();
+const primaryColor = config.visualdesign?.['primary-color'] || '#369';
+```
+
+### FontSelector
+
+Autocomplete input component for selecting fonts with support for Google Fonts, web-safe fonts, and generic font families.
+
+```tsx
+import { FontSelector } from '@pixelated-tech/components';
+
+<FontSelector
+  id="header-font-primary"
+  name="header-font-primary"
+  label="Header Font (Google Fonts)"
+  fontType="google"
+  value="Montserrat"
+  onChange={(font) => console.log('Selected font:', font)}
+/>
+```
+
+#### Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | - | Unique identifier for the input |
+| `name` | `string` | - | Name attribute for form submission |
+| `label` | `string` | - | Display label for the input |
+| `fontType` | `'google' \| 'websafe' \| 'generic'` | - | Type of fonts to show in autocomplete |
+| `value` | `string` | `''` | Current selected font value |
+| `onChange` | `function` | - | Callback when font selection changes |
+| `required` | `boolean` | `false` | Whether the field is required |
+| `placeholder` | `string` | - | Placeholder text (auto-generated based on fontType) |
+
+#### Font Types
+
+- **`google`**: Shows Google Fonts with live preview links
+- **`websafe`**: Shows common web-safe fonts (Arial, Helvetica, etc.)
+- **`generic`**: Shows CSS generic font families (serif, sans-serif, etc.)
+
+#### Features
+
+- **Autocomplete**: Intelligent font suggestions as you type
+- **Google Fonts Integration**: Direct links to Google Fonts preview pages
+- **Web-safe Fallbacks**: Ensures font availability across devices
+- **Generic Families**: CSS generic font family support
+- **Accessibility**: Proper labeling and keyboard navigation
+
+### ConfigEngine
+
+Components for rendering visual design styles and Google Fonts imports from configuration data.
+
+#### VisualDesignStyles
+
+Renders CSS custom properties from visual design configuration tokens.
+
+```tsx
+import { VisualDesignStyles } from '@pixelated-tech/components';
+
+<VisualDesignStyles visualdesign={{
+  'primary-color': '#007bff',
+  'header-font-primary': 'Montserrat',
+  'header-font-fallback': 'Arial',
+  'header-font-generic': 'sans-serif',
+  'font-size1-min': '14px',
+  'font-size1-max': '18px'
+}} />
+```
+
+**Generated CSS:**
+```css
+:root {
+  --primary-color: #007bff;
+  --header-font-family: "Montserrat", "Arial", "sans-serif";
+  --font-size1: clamp(var(--font-size1-min), calc(var(--font-size1-min) + ((var(--font-size1-max) - var(--font-size1-min)) * ((100vw - var(--font-min-screen)) / (var(--font-max-screen) - var(--font-min-screen))))), var(--font-size1-max));
+}
+h1 { font-size: var(--font-size1); }
+```
+
+#### GoogleFontsImports
+
+Automatically generates Google Fonts link tags for fonts specified in visual design configuration.
+
+```tsx
+import { GoogleFontsImports } from '@pixelated-tech/components';
+
+<GoogleFontsImports visualdesign={{
+  'header-font-primary': 'Montserrat',
+  'body-font-primary': 'Open Sans'
+}} />
+```
+
+**Generated HTML:**
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Montserrat|Open+Sans&display=swap" rel="stylesheet">
+```
+
+#### Features
+
+- **Font Stack Generation**: Automatically builds CSS font-family stacks from 3-field font configuration
+- **Responsive Typography**: Generates fluid font sizes using CSS clamp() for responsive design
+- **Google Fonts Integration**: Automatically imports only the Google Fonts used in the design
+- **Web-safe Font Filtering**: Excludes web-safe fonts from Google Fonts imports to reduce loading
+- **Server-safe**: Both components are safe to use in server components and API routes
+
 ---
 
 ## SEO & Schema