zuljaman-banner-components 1.0.23 → 1.0.24

package/README.md

@@ -4,14 +4,15 @@ Platform-agnostic banner components for Next.js and AWS Lambda platforms. This s
 
 ## Features
 
-- ✅ **Platform Agnostic**: Works with Next.js, AWS Lambda, and other React environments
-- ✅ **TypeScript Support**: Full TypeScript definitions with enhanced type safety
-- ✅ **Adapter Pattern**: Clean separation of platform-specific image handling
-- ✅ **Dynamic Font Sizing**: Automatic font size calculation based on content length
-- ✅ **Advanced Shadow Effects**: Gradient-based shadow system with randomization
-- ✅ **Multiple Styles**: Support for different banner styles and substyles
-- ✅ **Responsive Design**: Automatic scaling based on container dimensions
-- ✅ **Zero Dependencies**: Minimal external dependencies for maximum compatibility
+- **4 Banner Styles**: Each with 3 substyles (12 total variations)
+- **Flexible Copy System**: Array-based copies with per-copy styling (color, background, padding, etc.)
+- **Platform Agnostic**: Works with Next.js, AWS Lambda, and other React environments
+- **TypeScript Support**: Full TypeScript definitions with enhanced type safety
+- **Adapter Pattern**: Clean separation of platform-specific image handling
+- **Interactive Modes**: Drag, resize, rotate, and linking modes for visual editors
+- **Auto-Positioning**: Chain-based element positioning system
+- **Visual Effects**: Configurable text shadows, logo shadows, and noise overlays
+- **Responsive Design**: Automatic scaling based on container dimensions
 
 ## Installation
 
@@ -24,19 +25,24 @@ npm install @zuljaman/banner-components
 ### Next.js Usage
 
 ```typescript
-import { BannerVisor } from '@zuljaman/banner-components';
-import { ImageComponent } from '@zuljaman/banner-components/adapters/NextJSAdapter';
+import NextImage from 'next/image';
+import { BannerVisor, createNextJSAdapter } from '@zuljaman/banner-components';
+
+// Create platform adapter
+const ImageComponent = createNextJSAdapter(NextImage);
 
-function MyBannerComponent() {
+function MyBanner() {
   return (
     <BannerVisor
-      bannerStyle={1}
-      bannerSubstyle={1}
-      postType="POST"
-      copy1="Your primary text here"
-      copy2="Your secondary text here"
-      logoUrl="/path/to/logo.png"
-      backgroundImageUrl="/path/to/background.jpg"
+      bannerStyle={1}           // 1-4
+      bannerSubstyle={1}        // 1-3
+      postType="POST"           // "POST" or "STORY"
+      copies={[
+        { id: 'copy-1', text: 'Primary text', styleSlot: 0 },
+        { id: 'copy-2', text: 'Secondary text', styleSlot: 1 }
+      ]}
+      logoUrl="/logo.png"
+      backgroundImageUrl="/background.jpg"
       ImageComponent={ImageComponent}
     />
   );
@@ -46,98 +52,208 @@ function MyBannerComponent() {
 ### AWS Lambda / SSR Usage
 
 ```typescript
-import { BannerVisor } from '@zuljaman/banner-components';
-import { ImageComponent } from '@zuljaman/banner-components/adapters/SSRAdapter';
+import { BannerVisor, SSRImageComponent } from '@zuljaman/banner-components';
 
-function MyBannerComponent() {
+function LambdaBanner({ copies, logoUrl, backgroundImageUrl }) {
   return (
     <BannerVisor
       bannerStyle={1}
       bannerSubstyle={1}
       postType="POST"
-      copy1="Your primary text here"
-      copy2="Your secondary text here"
-      logoUrl="/path/to/logo.png"
-      backgroundImageUrl="/path/to/background.jpg"
-      ImageComponent={ImageComponent}
+      copies={copies}
+      logoUrl={logoUrl}
+      backgroundImageUrl={backgroundImageUrl}
+      ImageComponent={SSRImageComponent}
+      sizeMultiplier={1}  // Fixed size for server rendering
     />
   );
 }
 ```
 
-## Components
+### Legacy Props (Backward Compatible)
 
-### BannerVisor
-
-The main banner component that handles routing between different styles and substyles.
+```typescript
+// Still supported for backward compatibility
+<BannerVisor
+  bannerStyle={1}
+  bannerSubstyle={1}
+  postType="POST"
+  copy1="Primary text"      // Legacy: use copies[] instead
+  copy2="Secondary text"    // Legacy: use copies[] instead
+  logoUrl="/logo.png"
+  backgroundImageUrl="/background.jpg"
+  ImageComponent={ImageComponent}
+/>
+```
 
-**Props:**
-- `bannerStyle: number` - Style identifier (1-2)
-- `bannerSubstyle: number` - Substyle identifier (1-3)
-- `postType: PostType` - "POST" or "STORY" for different dimensions
-- `copy1?: string` - Primary text content
-- `copy2?: string` - Secondary text content
-- `logoUrl?: string` - URL for logo image
-- `backgroundImageUrl?: string` - URL for background image
-- `sizeMultiplier?: number` - Manual size scaling (optional)
-- `ImageComponent: React.ComponentType<ImageProps>` - Platform-specific image component
+## Architecture
 
-### Style Components
+```
+BannerVisor (Entry point)
+  └── BannerRenderer (Generic style-agnostic renderer)
+        ├── LogoElement → DraggableElement
+        ├── CopyElement → DraggableElement (one per copy)
+        ├── InteractiveLines (chain visualization)
+        └── VisualGuides (alignment guides)
+```
 
-#### BannerStyle1
-Enhanced banner style with sophisticated layout and shadow effects.
+### Key Components
 
-#### BannerStyle2
-Alternative banner style optimized for different content types.
+| Component | Description |
+|-----------|-------------|
+| `BannerVisor` | Main entry point, handles legacy prop conversion |
+| `BannerRenderer` | Generic renderer that works with all 4 styles |
+| `CopyElement` | Renders individual text elements with styling |
+| `LogoElement` | Renders logo with positioning |
+| `DraggableElement` | Reusable drag/rotate/resize wrapper |
 
-### Substyles
+## Props Reference
 
-Each style includes 3 substyles (BannerSubstyle1, BannerSubstyle2, BannerSubstyle3) with different layouts:
-- **Substyle 1**: Logo top-left, text bottom
-- **Substyle 2**: Logo top-left with side text, centered bottom text
-- **Substyle 3**: Logo and text side-by-side, bottom text
+### Core Props
 
-## Platform Adapters
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `bannerStyle` | `number` | `1` | Style template (1-4) |
+| `bannerSubstyle` | `number` | required | Substyle variation (1-3) |
+| `postType` | `'POST' \| 'STORY'` | required | Banner dimensions |
+| `ImageComponent` | `React.ComponentType` | required | Platform image adapter |
 
-### NextJSAdapter
-Uses Next.js optimized Image component with automatic optimization.
+### Copy System
 
 ```typescript
-import { ImageComponent } from '@zuljaman/banner-components/adapters/NextJSAdapter';
+interface CopyConfig {
+  id: string;                    // Unique identifier
+  styleSlot?: number;            // 0 = copy1 position, 1 = copy2 position
+  text: string;                  // Text content
+  fontSize?: number;             // Size multiplier (default 1.0)
+  align?: 'left' | 'center' | 'right';
+  fontWeight?: 'thin' | 'normal' | 'bold';
+  fontFamily?: string;
+  color?: string;                // Text color
+  bgColor?: string;              // Background color
+  hasBg?: boolean;               // Show background
+  paddingX?: string;             // Horizontal padding (e.g., '1rem')
+  paddingY?: string;             // Vertical padding
+  borderRadius?: string;         // Corner radius
+  translateX?: number;           // X offset in pixels
+  translateY?: number;           // Y offset in pixels
+  rotation?: number;             // Rotation in degrees
+  width?: number;                // Width in pixels
+  underline?: boolean;
+  italic?: boolean;
+  textBold?: boolean;
+  hidden?: boolean;              // Hide this copy
+}
 ```
 
-### SSRAdapter
-Uses standard HTML img tags for server-side rendering environments.
+### Visual Effects
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `textShadowEnabled` | `boolean` | from style | Enable text shadows |
+| `textShadowSize` | `number` | from style | Shadow blur size |
+| `textShadowIntensity` | `number` | from style | Shadow opacity |
+| `logoShadowEnabled` | `boolean` | from style | Enable logo shadow |
+| `logoShadowSize` | `number` | from style | Logo shadow size |
+| `logoShadowIntensity` | `number` | from style | Logo shadow opacity |
+| `noiseEnabled` | `boolean` | from style | Enable noise overlay |
+| `noiseIntensity` | `number` | from style | Noise opacity |
+
+### Interactive Modes
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `draggableMode` | `boolean` | Enable drag/rotate/resize on elements |
+| `creationMode` | `boolean` | Show element borders, enable creation UI |
+| `linkingModeActive` | `boolean` | Enable element linking via clicks |
+
+### Callbacks
 
 ```typescript
-import { ImageComponent } from '@zuljaman/banner-components/adapters/SSRAdapter';
+// Indexed callbacks (new)
+onCopyPositionChange?: (index: number, pos: { x: number; y: number }) => void;
+onCopyRotationChange?: (index: number, rotation: number) => void;
+onCopyWidthChange?: (index: number, width: number) => void;
+
+// Logo callbacks
+onLogoPositionChange?: (pos: { x: number; y: number }) => void;
+onLogoRotationChange?: (rotation: number) => void;
+onLogoWidthChange?: (width: number) => void;
+
+// Auto-positioning callbacks
+onApplyAutoPositioning?: (config) => void;
+onConnectionsDeleted?: () => void;
+onLineGapsChange?: (lineGaps: Record<string, number>) => void;
+
+// Legacy callbacks (still supported)
+onCopy1PositionChange?: (pos) => void;
+onCopy2PositionChange?: (pos) => void;
 ```
 
-## Utilities
+## Style Guide
 
-### Font Size Calculation
+### Available Styles
+
+| Style | Font | Recommended Copies | Noise | Description |
+|-------|------|-------------------|-------|-------------|
+| 1 | Roboto | 2 | No | Clean, modern sans-serif |
+| 2 | Lato | 2 | No | Styled text with backgrounds |
+| 3 | Cormorant Garamond | 1 | Yes | Elegant serif, single copy |
+| 4 | Cormorant Garamond | 2 | No | Dual serif copies |
+
+### Substyle Layouts
+
+Each style has 3 substyles (1-3) with different element arrangements:
+- **Substyle 1**: Logo top-left, text bottom
+- **Substyle 2**: Logo + side text, centered bottom
+- **Substyle 3**: Logo and text side-by-side
+
+## Auto-Positioning System
+
+The package includes a chain-based auto-positioning system for maintaining element relationships:
 
 ```typescript
-import { calculateStyleFontSizes } from '@zuljaman/banner-components';
-
-const fontSizes = calculateStyleFontSizes("Primary text", "Secondary text", {
-  baseSizeRem1: 4.8,
-  baseSizeRem2: 4.8,
-  maxLengthThreshold: 40,
-  reductionFactor: 0.15
-});
+// Elements are linked in chains: copy-0 → copy-1 → copy-2
+// When an anchor element moves, linked elements adjust automatically
+
+<BannerVisor
+  autoPositioningOverride={{
+    enabled: true,
+    config: {
+      links: [
+        { fromElement: 'copy-0', toElement: 'copy-1', direction: 'down', gapRem: 1 }
+      ]
+    },
+    gapRem: 1
+  }}
+  // ...other props
+/>
 ```
 
-### Shadow Effects
+### Element IDs
+
+- Logo: `'logo'`
+- Copies: `'copy-0'`, `'copy-1'`, `'copy-2'` (based on styleSlot)
+
+## Platform Adapters
+
+### NextJSAdapter
+
+Uses Next.js optimized Image component with automatic optimization.
 
 ```typescript
-import { createAbstractShadowStyle } from '@zuljaman/banner-components/styles';
+import NextImage from 'next/image';
+import { createNextJSAdapter } from '@zuljaman/banner-components';
+
+const ImageComponent = createNextJSAdapter(NextImage);
+```
+
+### SSRAdapter
+
+Uses standard HTML img tags for server-side rendering environments.
 
-const shadowStyle = createAbstractShadowStyle({
-  direction: "bottom",
-  size: "70%",
-  intensity: 0.8
-});
+```typescript
+import { SSRImageComponent } from '@zuljaman/banner-components';
 ```
 
 ## TypeScript Support
@@ -145,59 +261,61 @@ const shadowStyle = createAbstractShadowStyle({
 Full TypeScript definitions are included:
 
 ```typescript
-import type { 
+import type {
   BannerVisorProps,
-  BannerSubstyleProps,
+  CopyConfig,
   PostType,
   ImageProps,
-  StyleFontConfig
+  CustomSubstyleConfig,
+  CustomStyle
 } from '@zuljaman/banner-components';
 ```
 
-## Constants
+## Advanced Hooks
 
-```typescript
-import { 
-  DEFAULT_BANNER_WIDTH,
-  DEFAULT_BANNER_HEIGHT,
-  DEFAULT_STORY_WIDTH,
-  DEFAULT_STORY_HEIGHT,
-  STYLE_FONT_CONFIGS
-} from '@zuljaman/banner-components/constants';
-```
+The package includes several hooks for advanced use cases:
 
-## Migration Guide
+| Hook | Purpose |
+|------|---------|
+| `useAutoPositioning` | Manages element positioning chains |
+| `useDragSnap` | Provides rotation and position snapping |
+| `useLineDrawing` | Handles chain drawing interactions |
+| `useProximityDetection` | Detects element proximity for linking |
 
-### From Next.js App
+## Migration Guide
 
-Replace existing imports:
+### From Legacy copy1/copy2 Props
 
 ```typescript
 // Before
-import { BannerVisor } from '@/components/BannerStyles';
-
-// After
-import { BannerVisor } from '@zuljaman/banner-components';
-import { ImageComponent } from '@zuljaman/banner-components/adapters/NextJSAdapter';
-
-// Pass ImageComponent as prop
-<BannerVisor {...props} ImageComponent={ImageComponent} />
+<BannerVisor
+  copy1="Primary text"
+  copy2="Secondary text"
+  copy1FontSizeMultiplier={1.2}
+  copy2FontSizeMultiplier={1.0}
+  // ...
+/>
+
+// After (recommended)
+<BannerVisor
+  copies={[
+    { id: 'c1', text: 'Primary text', styleSlot: 0, fontSize: 1.2 },
+    { id: 'c2', text: 'Secondary text', styleSlot: 1, fontSize: 1.0 }
+  ]}
+  // ...
+/>
 ```
 
-### From AWS Lambda
-
-Replace existing imports:
+### From Old Adapter Imports
 
 ```typescript
-// Before
-import { BannerVisor } from '../components/BannerStyles/BannerVisor';
-
-// After
-import { BannerVisor } from '@zuljaman/banner-components';
-import { ImageComponent } from '@zuljaman/banner-components/adapters/SSRAdapter';
+// Before (incorrect)
+import { ImageComponent } from '@zuljaman/banner-components/adapters/NextJSAdapter';
 
-// Pass ImageComponent as prop
-<BannerVisor {...props} ImageComponent={ImageComponent} />
+// After (correct)
+import NextImage from 'next/image';
+import { createNextJSAdapter } from '@zuljaman/banner-components';
+const ImageComponent = createNextJSAdapter(NextImage);
 ```
 
 ## Development
@@ -209,7 +327,7 @@ npm install
 # Build the package
 npm run build
 
-# Watch for changes during development
+# Run playground (development)
 npm run dev
 
 # Clean build artifacts
@@ -219,24 +337,3 @@ npm run clean
 ## License
 
 MIT
-
-## Contributing
-
-This package consolidates banner components from multiple Zuljaman projects. When contributing:
-
-1. Ensure changes maintain backward compatibility
-2. Update TypeScript definitions
-3. Test with both Next.js and AWS Lambda adapters
-4. Follow existing code patterns and styling
-
-## Architecture
-
-The package uses an adapter pattern to handle platform-specific image components while maintaining shared logic for:
-
-- Font size calculations
-- Shadow effect generation
-- Layout and styling
-- Type definitions
-- Constants and configurations
-
-This approach ensures 100% code reuse while supporting platform-specific optimizations.

package/dist/components/BannerRenderer/BannerRenderer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * BannerRenderer component - Generic platform-agnostic banner renderer
+ * Unified component that handles all banner styles based on configuration
+ */
+import React from "react";
+import type { BannerRendererProps } from "./types";
+export declare const BannerRenderer: React.FC<BannerRendererProps>;
+//# sourceMappingURL=BannerRenderer.d.ts.map

package/dist/components/BannerRenderer/BannerRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BannerRenderer.d.ts","sourceRoot":"","sources":["../../../src/components/BannerRenderer/BannerRenderer.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAA+C,MAAM,OAAO,CAAC;AASpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAMnD,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CA8gBxD,CAAC"}