@qwickapps/react-framework 1.8.0 → 1.8.1

package/src/components/blocks/HeroSlideshow.tsx

@@ -0,0 +1,156 @@
+/**
+ * HeroSlideshow Component
+ *
+ * A slideshow built on top of HeroBlock that cycles through multiple slides
+ * with auto-rotation, fade transitions, and progress dot navigation.
+ *
+ * Usage (props-driven, e.g. qwickdocs):
+ *   <HeroSlideshow slides={[{ title: 'Slide 1', ... }, ...]} />
+ *
+ * Usage (CMS-driven, e.g. work-macha):
+ *   const slideshow = await payload.findByID({ collection: 'hero-slideshows', id });
+ *   <HeroSlideshow slides={slideshow.slides} autoPlayInterval={slideshow.autoPlayInterval} />
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+'use client';
+
+import React, { useState, useEffect, useCallback } from 'react';
+import { Box } from '@mui/material';
+import HeroBlock from './HeroBlock';
+import type { HeroBlockProps } from './HeroBlock';
+import type { ButtonProps } from '../buttons/Button';
+
+/**
+ * A single slide - subset of HeroBlockProps that drives visual content
+ */
+export interface HeroSlide {
+  /** Main headline text */
+  title: string;
+  /** Subtitle or description text */
+  subtitle?: string;
+  /** Background image URL */
+  backgroundImage?: string;
+  /** CSS gradient string, e.g. 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)' */
+  backgroundGradient?: string;
+  /** Theme color variant when no image/gradient set */
+  backgroundColor?: 'default' | 'primary' | 'secondary' | 'surface';
+  /** Call-to-action buttons */
+  actions?: ButtonProps[];
+  /** Overlay opacity when backgroundImage is set (0-1) */
+  overlayOpacity?: number;
+}
+
+export interface HeroSlideshowProps {
+  /** Array of slides to cycle through */
+  slides: HeroSlide[];
+  /** Auto-play interval in milliseconds. Default: 5000 */
+  autoPlayInterval?: number;
+  /** Show dot navigation. Default: true */
+  showDots?: boolean;
+  /** Height preset applied to all slides */
+  blockHeight?: HeroBlockProps['blockHeight'];
+  /** Text alignment applied to all slides */
+  textAlign?: HeroBlockProps['textAlign'];
+}
+
+const TRANSITION_DURATION = 300; // ms
+
+/**
+ * HeroSlideshow - Cycles through HeroBlock slides with fade transitions
+ */
+export function HeroSlideshow({
+  slides,
+  autoPlayInterval = 5000,
+  showDots = true,
+  blockHeight = 'large',
+  textAlign = 'center',
+}: HeroSlideshowProps) {
+  const [currentIndex, setCurrentIndex] = useState(0);
+  const [isVisible, setIsVisible] = useState(true);
+
+  const goToSlide = useCallback(
+    (index: number) => {
+      if (index === currentIndex) return;
+      setIsVisible(false);
+      setTimeout(() => {
+        setCurrentIndex(index);
+        setIsVisible(true);
+      }, TRANSITION_DURATION);
+    },
+    [currentIndex],
+  );
+
+  useEffect(() => {
+    if (slides.length <= 1 || autoPlayInterval <= 0) return;
+    const timer = setTimeout(() => {
+      goToSlide((currentIndex + 1) % slides.length);
+    }, autoPlayInterval);
+    return () => clearTimeout(timer);
+  }, [currentIndex, slides.length, autoPlayInterval, goToSlide]);
+
+  if (!slides.length) return null;
+
+  const slide = slides[currentIndex];
+
+  return (
+    <Box sx={{ position: 'relative', overflow: 'hidden' }}>
+      {/* Current slide with fade transition */}
+      <Box
+        sx={{
+          opacity: isVisible ? 1 : 0,
+          transition: `opacity ${TRANSITION_DURATION}ms ease-in-out`,
+        }}
+      >
+        <HeroBlock
+          title={slide.title}
+          subtitle={slide.subtitle}
+          backgroundImage={slide.backgroundImage}
+          backgroundGradient={slide.backgroundGradient}
+          backgroundColor={slide.backgroundColor}
+          actions={slide.actions}
+          overlayOpacity={slide.overlayOpacity}
+          blockHeight={blockHeight}
+          textAlign={textAlign}
+        />
+      </Box>
+
+      {/* Progress dots */}
+      {showDots && slides.length > 1 && (
+        <Box
+          sx={{
+            position: 'absolute',
+            bottom: 20,
+            left: '50%',
+            transform: 'translateX(-50%)',
+            display: 'flex',
+            gap: 1,
+            zIndex: 10,
+          }}
+        >
+          {slides.map((_, index) => (
+            <Box
+              key={index}
+              role="button"
+              aria-label={`Go to slide ${index + 1}`}
+              onClick={() => goToSlide(index)}
+              sx={{
+                width: index === currentIndex ? 28 : 8,
+                height: 8,
+                borderRadius: 4,
+                backgroundColor: 'rgba(255, 255, 255, 0.9)',
+                opacity: index === currentIndex ? 1 : 0.45,
+                cursor: 'pointer',
+                transition: 'all 0.3s ease',
+                '&:hover': { opacity: 0.8 },
+              }}
+            />
+          ))}
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+export default HeroSlideshow;

package/src/components/blocks/index.ts

@@ -11,6 +11,7 @@
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 export { default as HeroBlock } from './HeroBlock';
+export { default as HeroSlideshow } from './HeroSlideshow';
 export { default as Code } from './Code';
 export { default as Article } from './Article';
 export { default as Content } from './Content';
@@ -28,6 +29,7 @@ export { default as FeatureCard } from './FeatureCard';
 export { default as CardListGrid } from './CardListGrid';
 
 export type { HeroBlockProps } from './HeroBlock';
+export type { HeroSlideshowProps, HeroSlide } from './HeroSlideshow';
 export type { CodeProps } from './Code';
 export type { ArticleProps } from './Article';
 export type { ContentProps } from './Content';

package/src/components/layout/GridCellWrapper.tsx

@@ -55,22 +55,22 @@ const GridCellWrapper: React.FC<GridCellWrapperProps> = ({
   ...gridProps
 }) => {
   // If fullWidth is true, force size=12; otherwise build responsive size object for MUI v6
-  const responsiveSizing = fullWidth 
+  const responsiveSizing = fullWidth
     ? { size: 12 }
     : (() => {
-        const sizeConfig: unknown = {};
+        const sizeConfig: Partial<Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', number | 'auto'>> = {};
         if (xs !== undefined) sizeConfig.xs = xs;
         if (sm !== undefined) sizeConfig.sm = sm;
         if (md !== undefined) sizeConfig.md = md;
         if (lg !== undefined) sizeConfig.lg = lg;
         if (xl !== undefined) sizeConfig.xl = xl;
-        
+
         // If only one value provided, use it as a simple size value
         const definedBreakpoints = Object.keys(sizeConfig);
         if (definedBreakpoints.length === 1 && xs !== undefined && sm === undefined && md === undefined && lg === undefined && xl === undefined) {
           return { size: xs };
         }
-        
+
         return { size: sizeConfig };
       })();
 

package/src/schemas/transformers/ComponentTransformer.ts

@@ -420,7 +420,13 @@ export class ComponentTransformer {
    */
   private static transformElement(element: Element, key: string): ReactNode {
     const transformedNode = ComponentTransformer.transformHTMLElement(element);
-    if (transformedNode) return transformedNode;
+    if (transformedNode) {
+      // Clone the node and add the key prop
+      if (React.isValidElement(transformedNode)) {
+        return React.cloneElement(transformedNode, { key });
+      }
+      return transformedNode;
+    }
 
     const children = Array.from(element.children);
     const hasTransformableChildren = children.some(child =>

package/src/schemas/transformers/ReactNodeTransformer.ts

@@ -186,7 +186,7 @@ export class ReactNodeTransformer {
 
     // Use Html component to render HTML content safely
     const typedProps = props as Record<string, unknown>;
-    return createElement(Html, { key, children: typedProps.children });
+    return createElement(Html, { key, children: typedProps.children as ReactNode });
   }
 
   /**

package/src/stories/HeroSlideshow.stories.tsx

@@ -0,0 +1,164 @@
+/**
+ * HeroSlideshow Component Stories
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Meta, StoryObj } from '@storybook/react';
+import React from 'react';
+import QwickApp from '../components/QwickApp';
+import { HeroSlideshow } from '../components/blocks';
+import type { HeroSlide } from '../components/blocks/HeroSlideshow';
+
+// ─── Shared slide sets ──────────────────────────────────────────────────────
+
+const gradientSlides: HeroSlide[] = [
+  {
+    title: 'Build Apps 10x Faster',
+    subtitle: 'The most developer-friendly React framework. Production-ready in hours, not weeks.',
+    backgroundGradient: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+    actions: [
+      { label: 'Get Started', variant: 'primary', buttonSize: 'large' },
+      { label: 'View Docs', variant: 'outlined', buttonSize: 'large' },
+    ],
+  },
+  {
+    title: 'Schema-Driven Components',
+    subtitle: 'Define once in Payload CMS, render everywhere. Data binding built in.',
+    backgroundGradient: 'linear-gradient(135deg, #f093fb 0%, #f5576c 100%)',
+    actions: [
+      { label: 'See Components', variant: 'primary', buttonSize: 'large' },
+    ],
+  },
+  {
+    title: 'Ship With Confidence',
+    subtitle: 'Storybook-documented components, TypeScript-first, MUI-powered.',
+    backgroundGradient: 'linear-gradient(135deg, #4facfe 0%, #00f2fe 100%)',
+    actions: [
+      { label: 'Browse Storybook', variant: 'primary', buttonSize: 'large' },
+      { label: 'GitHub', variant: 'text', buttonSize: 'large' },
+    ],
+  },
+];
+
+const imageSlides: HeroSlide[] = [
+  {
+    title: 'Connect Talent with Opportunity',
+    subtitle: 'WorkMacha bridges restaurant owners and culinary students for short-term gigs.',
+    backgroundImage: 'https://images.unsplash.com/photo-1414235077428-338989a2e8c0?w=1400&q=80',
+    overlayOpacity: 0.55,
+    actions: [
+      { label: 'Post a Job', variant: 'primary', buttonSize: 'large' },
+      { label: 'Find Work', variant: 'outlined', buttonSize: 'large' },
+    ],
+  },
+  {
+    title: 'Build Your Culinary Portfolio',
+    subtitle: 'Every gig you complete earns a verified certificate you can share with employers.',
+    backgroundImage: 'https://images.unsplash.com/photo-1556910103-1c02745aec4b?w=1400&q=80',
+    overlayOpacity: 0.55,
+    actions: [
+      { label: 'Browse Jobs', variant: 'primary', buttonSize: 'large' },
+    ],
+  },
+  {
+    title: 'Hire the Right Talent, Fast',
+    subtitle: 'Verified culinary students available for shifts, events, and pop-ups.',
+    backgroundImage: 'https://images.unsplash.com/photo-1590846406792-0adc7f938f1d?w=1400&q=80',
+    overlayOpacity: 0.5,
+    actions: [
+      { label: 'Start Hiring', variant: 'primary', buttonSize: 'large' },
+    ],
+  },
+];
+
+// ─── Meta ────────────────────────────────────────────────────────────────────
+
+const meta: Meta<typeof HeroSlideshow> = {
+  title: 'Blocks/HeroSlideshow',
+  component: HeroSlideshow,
+  decorators: [
+    (Story) => (
+      <QwickApp appName="Storybook" appId="storybook" enableScaffolding={false}>
+        <Story />
+      </QwickApp>
+    ),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+  },
+  argTypes: {
+    autoPlayInterval: {
+      control: { type: 'number', min: 0, max: 10000, step: 500 },
+      description: 'Auto-advance interval in ms. Set to 0 to disable.',
+    },
+    showDots: { control: 'boolean' },
+    blockHeight: {
+      control: { type: 'select' },
+      options: ['small', 'medium', 'large', 'viewport'],
+    },
+    textAlign: {
+      control: { type: 'select' },
+      options: ['left', 'center', 'right'],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof HeroSlideshow>;
+
+// ─── Stories ─────────────────────────────────────────────────────────────────
+
+export const GradientSlides: Story = {
+  name: 'Gradient slides (props-driven)',
+  args: {
+    slides: gradientSlides,
+    autoPlayInterval: 4000,
+    showDots: true,
+    blockHeight: 'large',
+    textAlign: 'center',
+  },
+};
+
+export const ImageSlides: Story = {
+  name: 'Image slides (WorkMacha style)',
+  args: {
+    slides: imageSlides,
+    autoPlayInterval: 5000,
+    showDots: true,
+    blockHeight: 'large',
+    textAlign: 'center',
+  },
+};
+
+export const SingleSlide: Story = {
+  name: 'Single slide (no dots, no auto-play)',
+  args: {
+    slides: [gradientSlides[0]],
+    autoPlayInterval: 0,
+    showDots: false,
+    blockHeight: 'medium',
+    textAlign: 'center',
+  },
+};
+
+export const SlowAutoPlay: Story = {
+  name: 'Slow auto-play (8 second interval)',
+  args: {
+    slides: gradientSlides,
+    autoPlayInterval: 8000,
+    showDots: true,
+    blockHeight: 'medium',
+  },
+};
+
+export const LeftAligned: Story = {
+  name: 'Left-aligned content',
+  args: {
+    slides: imageSlides,
+    autoPlayInterval: 5000,
+    showDots: true,
+    blockHeight: 'large',
+    textAlign: 'left',
+  },
+};