documentation

Author: zerox80

src/components/cms/EditableImage.jsx

@@ -3,9 +3,24 @@ import { useEdit } from '../../context/EditContext'
 import { useContent } from '../../context/ContentContext'
 import { Image } from 'lucide-react'
 
+/**
+ * A CMS-integrated component for inline image editing.
+ * 
+ * Displays an image with a hover overlay when site editing is enabled.
+ * Standard implementation uses a simple URL prompt, but is designed to be
+ * extended with a full media picker.
+ * 
+ * @param {Object} props
+ * @param {string} props.section - The CMS section containing this image data.
+ * @param {string} props.field - Path to the image URL field within the section.
+ * @param {string} props.src - Initial image source URL.
+ * @param {string} props.alt - Accessibility alt text.
+ * @param {string} [props.className=''] - CSS classes for the image element itself.
+ * @param {string} [props.containerClassName=''] - CSS classes for the wrapper div.
+ */
 const EditableImage = ({
     section,
-    field, // e.g. 'heroImage' or 'features[0].icon' (though icon is not image usually)
+    field,
     src,
     alt,
     className = '',
@@ -20,34 +35,44 @@ const EditableImage = ({
         setCurrentSrc(src)
     }, [src])
 
+    /**
+     * Triggers the image update flow.
+     * 
+     * Handles deep cloning and traversal logic identical to EditableText,
+     * ensuring that image paths at any depth are correctly updated and synced.
+     */
     const handleEdit = async () => {
-        // Simple prompt for now. Ideally this would be a media picker.
+        // UI Interaction: Request new image URL from the user
         const newUrl = window.prompt("Enter new image URL:", currentSrc)
+
         if (newUrl && newUrl !== currentSrc) {
+            // Optimistic update of the local image source
             setCurrentSrc(newUrl)
 
             try {
+                // Step 1: Deep clone the section state
                 const sectionData = getSection(section)
-
-                // Deep clone to avoid mutating state directly
                 const updatedSection = JSON.parse(JSON.stringify(sectionData))
 
-                // Helper to set nested value
-                // We need to handle nested fields like 'brand.icon' or simple 'heroImage'
+                // Step 2: Traverse keys to reach the specific image field
                 const keys = field.split('.')
                 let target = updatedSection
                 for (let i = 0; i < keys.length - 1; i++) {
                     if (!target[keys[i]]) target[keys[i]] = {}
                     target = target[keys[i]]
                 }
+
+                // Step 3: Set new URL at the target path
                 target[keys[keys.length - 1]] = newUrl
 
+                // Step 4: Commit changes to global state and backend
                 await updateSection(section, updatedSection)
 
             } catch (err) {
-                console.error('Failed to update image:', err)
-                alert('Failed to save image update')
-                setCurrentSrc(src) // Revert
+                console.error('CMS: Failed to update image', err)
+                alert('Failed to save image update. Please check console.')
+                // Revert UI to previous state on error
+                setCurrentSrc(src)
             }
         }
     }

src/components/cms/EditableText.jsx

@@ -2,6 +2,22 @@ import React, { useState, useEffect } from 'react'
 import { useEdit } from '../../context/EditContext'
 import { useContent } from '../../context/ContentContext'
 
+/**
+ * A highly flexible, inline editable text component integrated with the CMS.
+ * 
+ * This component automatically switches between a display state (plain text) 
+ * and an edit state (input/textarea) based on the global `isEditing` context.
+ * It handles its own internal state during editing and commits changes to the 
+ * global content state on blur.
+ * 
+ * @param {Object} props
+ * @param {string} props.section - The CMS content section name (e.g., 'hero', 'footer').
+ * @param {string} props.field - The specific field path within the section (e.g., 'title', 'features.0.title').
+ * @param {string} props.value - The initial fallback value if no CMS data exists.
+ * @param {boolean} [props.multiline=false] - Whether to use a textarea instead of a text input.
+ * @param {string} [props.className=''] - Additional CSS classes for the wrapper component.
+ * @param {React.ElementType} [props.as='span'] - The HTML element or component to render as (e.g., 'h1', 'div').
+ */
 const EditableText = ({
     section,
     field,
@@ -21,29 +37,41 @@ const EditableText = ({
         setInternalValue(value)
     }, [value])
 
+    /**
+     * Commits the edited value back to the CMS backend.
+     * 
+     * Uses a deep-cloning strategy to preserve data integrity when updating 
+     * nested fields (paths like "array.0.field").
+     */
     const handleBlur = async () => {
+        // Skip update if value hasn't changed
         if (internalValue === currentValue) return
 
         try {
+            // Step 1: Fetch current state of the entire section
             const sectionData = getSection(section)
-            // Deep clone to avoid mutating state directly
+
+            // Step 2: Deep clone to avoid direct mutation of the global state object
             const updatedSection = JSON.parse(JSON.stringify(sectionData))
 
+            // Step 3: Traverse the object tree using the dot-notated field path
             const keys = field.split('.')
             let target = updatedSection
             for (let i = 0; i < keys.length - 1; i++) {
+                // Ensure intermediate objects exist
                 if (!target[keys[i]]) target[keys[i]] = {}
                 target = target[keys[i]]
             }
+
+            // Step 4: Set the new value at the leaf node
             target[keys[keys.length - 1]] = internalValue
 
+            // Step 5: Persist via the content context (API call + State Sync)
             await updateSection(section, updatedSection)
-            // On success, currentValue will update via props eventually,
-            // but for immediate feedback we can set it here too if we want,
-            // though typically we rely on the prop update from parent re-render.
         } catch (err) {
-            console.error('Failed to save', err)
-            setInternalValue(currentValue) // Revert on error
+            console.error('CMS: Failed to save changes', err)
+            // Revert UI to last known good value on failure
+            setInternalValue(currentValue)
         }
     }
 

src/components/landing/LandingCTA.jsx

@@ -1,8 +1,17 @@
 import React from 'react'
 import { useNavigate } from 'react-router-dom'
-
 import EditableText from '../cms/EditableText'
 
+/**
+ * The final "Call to Action" section for the landing page.
+ * 
+ * Features a high-contrast design with an animated aurora background
+ * to draw the user's attention towards the primary conversion button.
+ * 
+ * @param {Object} props
+ * @param {Object} props.content - Content object containing title and description.
+ * @param {string} [props.section='cta_section'] - CMS section identifier.
+ */
 const LandingCTA = ({ content, section = 'cta_section' }) => {
     const navigate = useNavigate()
     const ctaContent = content || {}

src/components/landing/LandingFeatures.jsx

@@ -3,19 +3,38 @@ import { Terminal, Cpu, Globe, Lock, Palette, Zap } from 'lucide-react'
 
 import EditableText from '../cms/EditableText'
 
+/**
+ * Displays a feature grid on the landing page using a modern Bento layout.
+ * 
+ * This component is highly dynamic; it accepts a `features` array from the CMS
+ * and maps them into interactive FeatureCards. It uses `EditableText` extensively 
+ * to allow real-time content updates.
+ * 
+ * @param {Object} props
+ * @param {Array} props.features - Array of feature objects (title, description, icon, bg, color).
+ * @param {string} [props.section='hero'] - The CMS section where these features are stored.
+ */
 const LandingFeatures = ({ features, section = 'hero' }) => {
-    // Use features from props, or empty array if not provided
+    // Robustness: Ensure features is always an array to prevent mapping errors
     const displayFeatures = Array.isArray(features) ? features : []
 
     return (
         <section id="features" className="py-24 relative overflow-hidden">
             <div className="container px-6 mx-auto relative z-10">
                 <div className="text-center max-w-2xl mx-auto mb-16">
                     <h2 className="section-title">
-                        <EditableText section="hero" field="features_title" value="Everything you need to " className="text-white" />
-                        <span className="gradient-text-aurora ml-2">
-                            <EditableText section="hero" field="features_highlight" value="scale" />
-                        </span>
+                        <EditableText
+                            section="hero"
+                            field="features_title"
+                            value="Everything you need to "
+                            className="text-white"
+                        />
+                        <EditableText
+                            section="hero"
+                            field="features_highlight"
+                            value="scale"
+                            className="gradient-text-aurora ml-2"
+                        />
                     </h2>
                     <p className="text-slate-400 text-lg">
                         <EditableText section="hero" field="features_subtitle" value="Powerful features packaged in a beautiful interface." />
@@ -33,8 +52,21 @@ const LandingFeatures = ({ features, section = 'hero' }) => {
     )
 }
 
+/**
+ * An individual card within the Bento grid.
+ * 
+ * Features micro-animations, glassmorphism styling, and dynamic color/icon injection.
+ * 
+ * @param {Object} props
+ * @param {Object} props.feature - The feature data object.
+ * @param {number} props.index - The index in the array (used for staggered animations).
+ * @param {string} props.section - Parent section name for CMS updates.
+ */
 const FeatureCard = ({ feature, index, section }) => {
+    // Default to 'Star' icon if specific icon name is missing or invalid
     const Icon = feature.icon || Star
+
+    // Layout Logic: Large features span two columns in the grid
     const isLarge = feature.size === 'large'
 
     return (

src/components/landing/LandingHero.jsx

@@ -6,13 +6,31 @@ import { Link, useNavigate, useLocation } from 'react-router-dom'
 import { useTranslation } from 'react-i18next'
 import { navigateContentTarget } from '../../utils/contentNavigation'
 
+/**
+ * The primary hero section for the landing page.
+ * 
+ * Features:
+ * - Parallax mouse-tracking effects for depth.
+ * - Dynamic CMS content integration with multi-layered fallbacks (CMS -> i18n -> Hardcoded).
+ * - Interactive透视 (perspective) 3D card animation for the dashboard preview.
+ * - Integrated `EditableText` and `EditableImage` for real-time site editing.
+ * 
+ * @param {Object} props
+ * @param {Object} props.content - Hero content from the CMS backend.
+ */
 const LandingHero = ({ content }) => {
     const { t } = useTranslation()
     const navigate = useNavigate()
     const location = useLocation()
+
+    // State for the interactive parallax mouse effect
     const [mousePosition, setMousePosition] = useState({ x: 0, y: 0 })
 
     useEffect(() => {
+        /**
+         * Tracks global mouse movement to update the parallax effect.
+         * Values are normalized to a small range (0-20) for subtle animation.
+         */
         const handleMouseMove = (e) => {
             setMousePosition({
                 x: (e.clientX / window.innerWidth) * 20,
@@ -23,7 +41,10 @@ const LandingHero = ({ content }) => {
         return () => window.removeEventListener('mousemove', handleMouseMove)
     }, [])
 
-    // Safe defaults from content or fallbacks
+    // Logic: Content Fallback Hierarchy
+    // 1. Check CMS provided content
+    // 2. Fallback to i18next translation keys
+    // 3. Last resort: Hardcoded English strings
     const titleLine1 = content?.title?.line1 || t('hero.title') || "Publish Stories"
     const titleLine2 = content?.title?.line2 || t('hero.subtitle') || "That Matter"
     const subtitle = content?.subtitle || t('hero.description')

src/components/landing/LandingStats.jsx

@@ -1,9 +1,18 @@
 import React from 'react'
-
 import EditableText from '../cms/EditableText'
 
+/**
+ * A horizontal statistics bar with glassmorphism styling.
+ * 
+ * Uses a responsive grid that adjusts from 2 to 4 columns based on screen size.
+ * Features a custom `divide-x` border styling to separate stat items.
+ * 
+ * @param {Object} props
+ * @param {Array} props.stats - Array of stat objects { value, label }.
+ * @param {string} [props.section='stats'] - CMS section identifier.
+ */
 const LandingStats = ({ stats, section = 'stats' }) => {
-    // Use stats from props
+    // Robustness: Ensure stats is an array to avoid crashes if content is missing
     const displayStats = Array.isArray(stats) ? stats : []
 
     return (

src/components/layout/Footer.jsx

@@ -6,6 +6,14 @@ import { navigateContentTarget } from '../../utils/contentNavigation'
 import { getIconComponent } from '../../utils/iconMap'
 import { sanitizeExternalUrl } from '../../utils/urlValidation'
 
+/**
+ * Smart icon resolver for contact links.
+ * 
+ * Attempts to guess the appropriate Lucide icon based on:
+ * 1. Explicitly defined icon in CMS
+ * 2. URL protocol (mailto:, tel:)
+ * 3. Domain detection (github.com)
+ */
 const resolveContactFallbackIcon = (contact) => {
     if (!contact) {
         return 'Terminal'
@@ -80,6 +88,14 @@ const Footer = () => {
         return allItems
     }, [staticNavigationItems, dynamicNavigationItems, navigation?.items])
 
+    /**
+     * Normalizes various link target types into a standard browser href.
+     * 
+     * Handles:
+     * - `section`: Prepends # for anchor navigation.
+     * - `route`/`page`: Internal SPA routing paths.
+     * - `external`: Validates and sanitizes third-party URLs.
+     */
     const buildTargetHref = useCallback((target) => {
         if (!target || typeof target !== 'object') {
             return null
@@ -204,11 +220,15 @@ const Footer = () => {
             .filter(Boolean)
     }, [buildTargetHref, effectiveNavigationItems, footerContent?.quickLinks])
 
+    /**
+     * Centralized click handler for footer links.
+     * 
+     * Leverages `navigateContentTarget` for SPA-friendly section/route jumps
+     * and falls back to standard anchor behavior for external/protocol links.
+     */
     const handleQuickLink = (event, link) => {
-        // Early return for invalid or missing link data
         if (!link) return
 
-        // Extract navigation data from link object
         const target = link.target
 
         if (target) {
@@ -219,11 +239,11 @@ const Footer = () => {
 
         const href = sanitizeExternalUrl(link.href || link.url)
         if (href) {
+            // Check for protocols that should NOT be intercepted by the SPA router
             const isExternal = href.startsWith('http://') || href.startsWith('https://')
             const isSpecialProtocol = href.startsWith('mailto:') || href.startsWith('tel:')
 
             if (isExternal || isSpecialProtocol) {
-                // Allow default anchor behavior
                 return
             }