nextworks 0.0.1 → 0.1.0-alpha.0

package/dist/kits/blocks/components/sections/HeroOverlay.tsx

@@ -0,0 +1,358 @@
+"use client";
+
+import React from "react";
+import Image from "next/image";
+import Link from "next/link";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+
+/**
+ * Props for the HeroOverlay component.
+ *
+ * @remarks
+ * - Prefer the structured image prop (image) over deprecated flat props.
+ * - Slot-style className overrides are merged after defaults via cn().
+ * - Motion controls affect CTA hover transitions.
+ *
+ * @public
+ */
+export interface HeroOverlayProps {
+  id?: string;
+  className?: string;
+
+  // New structured image props (aligns with HeroSplit)
+  image?: {
+    src?: string;
+    alt?: string;
+    className?: string;
+    objectFit?: React.CSSProperties["objectFit"];
+    objectPosition?: React.CSSProperties["objectPosition"];
+  };
+
+  // Deprecated flat image props (kept for backward compatibility)
+  /** @deprecated Use image.src instead */
+  imageSrc?: string;
+  /** @deprecated Use image.alt instead */
+  imageAlt?: string;
+  /** @deprecated Use image.objectFit instead */
+  imageObjectFit?: React.CSSProperties["objectFit"];
+  /** @deprecated Use image.objectPosition instead */
+  imageObjectPosition?: React.CSSProperties["objectPosition"];
+
+  // Allow string or object form like HeroSplit
+  heading?: string | { text?: string; className?: string };
+  subheading?: string | { text?: string; className?: string };
+  overlayRGBA?: string;
+  overlayDarkRGBA?: string;
+
+  // Alias to match HeroSplit naming
+  section?: { className?: string };
+  container?: { className?: string };
+  imageContainer?: { className?: string };
+  overlay?: { className?: string };
+  content?: { className?: string };
+  textContainer?: { className?: string };
+
+  // Retained styles; merged with heading/subheading.className when provided
+  /** @deprecated Use heading.className */
+  headingStyle?: { className?: string };
+  /** @deprecated Use subheading.className */
+  subheadingStyle?: { className?: string };
+
+  ctaContainer?: { className?: string };
+
+  // CTA objects now support label/href (aligns with HeroSplit)
+  cta1?: {
+    label?: string;
+    href?: string;
+    variant?:
+      | "default"
+      | "destructive"
+      | "outline"
+      | "secondary"
+      | "ghost"
+      | "link";
+    size?: "default" | "sm" | "lg" | "icon";
+    className?: string;
+    unstyled?: boolean;
+    style?: React.CSSProperties;
+  };
+  cta2?: {
+    label?: string;
+    href?: string;
+    variant?:
+      | "default"
+      | "destructive"
+      | "outline"
+      | "secondary"
+      | "ghost"
+      | "link";
+    size?: "default" | "sm" | "lg" | "icon";
+    className?: string;
+    unstyled?: boolean;
+    style?: React.CSSProperties;
+  };
+
+  // Deprecated CTA props (kept for backward compatibility)
+  /** @deprecated Use cta1.label instead */
+  ctaBtn1Label?: string;
+  /** @deprecated Use cta1.href instead */
+  ctaBtn1Href?: string;
+  /** @deprecated Use cta2.label instead */
+  ctaBtn2Label?: string;
+  /** @deprecated Use cta2.href instead */
+  ctaBtn2Href?: string;
+
+  ariaLabel?: string;
+
+  // Motion control for CTA buttons
+  enableMotion?: boolean;
+}
+
+/**
+ * Full-bleed image hero with color overlay, heading/subheading, and up to two CTAs.
+ *
+ * @remarks
+ * - Styling: slot-style overrides for container, imageContainer, overlay, content, textContainer.
+ * - Motion: enableMotion applies hover-lift transitions to CTA buttons only.
+ * - Accessibility: uses semantic <section> with aria-label; background image is
+ *   decorative with overlay and text content provided separately.
+ *
+ * @example
+ * <HeroOverlay
+ *   image={{ src: "/hero.png", alt: "" }}
+ *   heading="Welcome"
+ *   subheading="Build faster with our blocks"
+ *   cta1={{ label: "Get Started", href: "#getstarted" }}
+ * />
+ */
+export function HeroOverlay({
+  id,
+  className,
+
+  // Deprecated flat image defaults (still supported)
+  imageSrc = "/hero.png",
+  imageAlt = "Hero background image",
+  imageObjectFit = "cover",
+  imageObjectPosition = "center",
+
+  // New structured image (optional)
+  image,
+
+  // Keep string defaults; object form supported
+  heading = "Lorem ipsum dolor sit amet, consectetur",
+  subheading = "Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.",
+  overlayRGBA = "rgba(255, 255, 255, 0.8)",
+  overlayDarkRGBA = "rgba(0, 0, 0, 0.8)",
+
+  // Deprecated CTA label/href (still supported)
+  ctaBtn1Label = "Get Started",
+  ctaBtn1Href = "#getstarted",
+  ctaBtn2Label,
+  ctaBtn2Href,
+
+  // Layout containers
+  container = { className: "relative h-[440px] md:h-[500px] w-full" },
+  // container = { className: "relative h-[500px] md:h-[600px] w-full" },
+  section,
+  imageContainer = { className: "absolute inset-0" },
+  overlay = { className: "absolute inset-0 z-10 pointer-events-none" },
+  content = {
+    className:
+      "relative z-20 h-full w-full flex flex-col justify-start items-center pt-14 pb-8 px-8",
+  },
+  textContainer = { className: "max-w-4xl space-y-6 text-center" },
+
+  // Typography defaults (deprecated props still merged)
+  headingStyle = { className: "" },
+  subheadingStyle = { className: "" },
+
+  // CTA containers and variants
+  ctaContainer = {
+    className:
+      "flex flex-col sm:flex-row gap-4 mt-6 justify-center items-center",
+  },
+  cta1,
+  cta2,
+
+  ariaLabel = "Hero section",
+  enableMotion = true,
+}: HeroOverlayProps) {
+  // Merge new structured image with deprecated flat props
+  const effImage = {
+    src: image?.src ?? imageSrc,
+    alt: image?.alt ?? imageAlt,
+    objectFit: image?.objectFit ?? imageObjectFit,
+    objectPosition: image?.objectPosition ?? imageObjectPosition,
+    className: image?.className,
+  };
+
+  // Defaults and normalization like HeroSplit
+  const defaultHeading = {
+    text: "Lorem ipsum dolor sit amet, consectetur",
+    className:
+      "text-4xl md:text-5xl font-bold text-center leading-tight text-foreground",
+  };
+  const defaultSubheading = {
+    text: "Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.",
+    className:
+      "text-xl md:text-2xl text-center text-foreground leading-relaxed",
+  };
+
+  const normalizedHeading =
+    typeof heading === "string"
+      ? {
+          text: heading,
+          className: cn(defaultHeading.className, headingStyle?.className),
+        }
+      : {
+          text: heading?.text ?? defaultHeading.text,
+          className: cn(
+            defaultHeading.className,
+            headingStyle?.className,
+            heading?.className,
+          ),
+        };
+
+  const normalizedSubheading =
+    typeof subheading === "string"
+      ? {
+          text: subheading,
+          className: cn(
+            defaultSubheading.className,
+            subheadingStyle?.className,
+          ),
+        }
+      : {
+          text: subheading?.text ?? defaultSubheading.text,
+          className: cn(
+            defaultSubheading.className,
+            subheadingStyle?.className,
+            subheading?.className,
+          ),
+        };
+
+  // Motion class for CTA buttons
+  const buttonLift = enableMotion
+    ? "transition-all duration-200 hover:-translate-y-0.5"
+    : "transition-none hover:!translate-y-0";
+
+  // CTA defaults and normalization (merge, don't replace).
+  const defaultCta1 = {
+    label: ctaBtn1Label,
+    href: ctaBtn1Href,
+    variant: "default" as const,
+    size: "lg" as const,
+    className: "",
+  };
+  const defaultCta2 = {
+    label: ctaBtn2Label,
+    href: ctaBtn2Href,
+    variant: "outline" as const,
+    size: "lg" as const,
+    className: "",
+  };
+
+  const mergedCta1 = {
+    ...defaultCta1,
+    ...(cta1 ?? {}),
+    className: cn(defaultCta1.className, cta1?.className, buttonLift),
+  };
+  const mergedCta2 =
+    cta2 || ctaBtn2Label || ctaBtn2Href
+      ? {
+          ...defaultCta2,
+          ...(cta2 ?? {}),
+          className: cn(defaultCta2.className, cta2?.className, buttonLift),
+        }
+      : undefined;
+
+  // buttonLift defined above
+
+  // Merge alias section.className with container.className
+  const finalContainerClass = cn(container.className, section?.className);
+
+  const showCta2 = !!mergedCta2?.label;
+
+  return (
+    <section
+      id={id}
+      className={cn(finalContainerClass, className)}
+      aria-label={ariaLabel}
+    >
+      <div className={imageContainer.className}>
+        <Image
+          src={effImage.src!}
+          alt={effImage.alt!}
+          fill
+          sizes="100vw"
+          quality={75}
+          priority
+          className={effImage.className}
+          style={{
+            objectFit: effImage.objectFit,
+            objectPosition: effImage.objectPosition,
+          }}
+        />
+      </div>
+
+      <div
+        className={overlay.className}
+        style={{ backgroundColor: overlayRGBA }}
+        aria-hidden
+      />
+      <div
+        className={cn(overlay.className, "hidden dark:block")}
+        style={{ backgroundColor: overlayDarkRGBA }}
+        aria-hidden
+      />
+
+      <div className={content.className}>
+        <div className={textContainer.className}>
+          <h1 className={normalizedHeading.className}>
+            {normalizedHeading.text}
+          </h1>
+          <p className={normalizedSubheading.className}>
+            {normalizedSubheading.text}
+          </p>
+          <div className={ctaContainer.className}>
+            {mergedCta1.label && (
+              <Button
+                asChild
+                variant={mergedCta1.variant}
+                size={mergedCta1.size}
+                className={mergedCta1.className}
+                unstyled={mergedCta1.unstyled}
+                style={mergedCta1.style}
+              >
+                <Link
+                  href={mergedCta1.href || "#"}
+                  aria-label={mergedCta1.label}
+                >
+                  {mergedCta1.label}
+                </Link>
+              </Button>
+            )}
+            {showCta2 && (
+              <Button
+                asChild
+                variant={mergedCta2!.variant}
+                size={mergedCta2!.size}
+                className={mergedCta2!.className}
+                unstyled={mergedCta2!.unstyled}
+                style={mergedCta2!.style}
+              >
+                <Link
+                  href={mergedCta2!.href || "#"}
+                  aria-label={mergedCta2!.label}
+                >
+                  {mergedCta2!.label}
+                </Link>
+              </Button>
+            )}
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}

package/dist/kits/blocks/components/sections/HeroSplit.tsx

@@ -0,0 +1,352 @@
+"use client";
+import React from "react";
+import Image from "next/image";
+import Link from "next/link";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+
+/**
+ * Props for the HeroSplit component.
+ *
+ * @remarks
+ * - Layout: split hero with text and image. imageLayout controls whether the
+ *   image is full-bleed or padded.
+ * - Styling: slot-style className overrides are merged via cn(). Heading and
+ *   subheading accept either a string or a { text, className } object.
+ * - Motion: enableMotion toggles button hover lift transitions.
+ * - Accessibility: uses a semantic <section> with aria-label.
+ */
+interface HeroSplitProps {
+  /** Optional id to attach to the root section element */
+  id?: string;
+  /** Optional top-level class to override the root */
+  className?: string;
+  /** Section slot override */
+  section?: { className?: string };
+  /** Heading string or object with text and className */
+  heading?: string | { text?: string; className?: string };
+  /** Subheading string or object with text and className */
+  subheading?: string | { text?: string; className?: string };
+  /** Primary CTA configuration */
+  cta1?: {
+    label?: string;
+    href?: string;
+    variant?:
+      | "default"
+      | "destructive"
+      | "outline"
+      | "secondary"
+      | "ghost"
+      | "link";
+    size?: "default" | "sm" | "lg" | "icon";
+    className?: string;
+    /** When true, renders the Button in unstyled mode to avoid token bleed from variants */
+    unstyled?: boolean;
+    /** Optional inline style forwarded to Button */
+    style?: React.CSSProperties;
+  };
+  /** Secondary CTA configuration */
+  cta2?: {
+    label?: string;
+    href?: string;
+    variant?:
+      | "default"
+      | "destructive"
+      | "outline"
+      | "secondary"
+      | "ghost"
+      | "link";
+    size?: "default" | "sm" | "lg" | "icon";
+    className?: string;
+    /** When true, renders the Button in unstyled mode to avoid token bleed from variants */
+    unstyled?: boolean;
+    /** Optional inline style forwarded to Button */
+    style?: React.CSSProperties;
+  };
+  /** Image configuration */
+  image?: { src?: string; alt?: string; className?: string };
+  /** Image container slot */
+  imageContainer?: { className?: string };
+  /** Text container slot */
+  textContainer?: { className?: string };
+  /** Buttons container slot */
+  buttonsContainer?: { className?: string };
+  /** Text alignment at large breakpoints. @defaultValue "center" */
+  textAlign?: "left" | "center" | "right";
+  /** Fallback node shown when no image.src is provided */
+  fallback?: React.ReactNode;
+  /** ARIA label for the section. @defaultValue "Hero section" */
+  ariaLabel?: string;
+  /** When false, removes button hover lifts, keeps layout static */
+  enableMotion?: boolean;
+  /** "padded" keeps default gutters. "full-bleed" allows the image to touch page edges. @defaultValue "full-bleed" */
+  imageLayout?: "padded" | "full-bleed";
+}
+
+/**
+ * Split hero with text on one side and an image on the other.
+ *
+ * @remarks
+ * - Text props accept string or object forms to easily override classes.
+ * - Full-bleed layout absolutely positions the image on larger screens.
+ * - Motion only affects the subtle hover lift on CTA buttons.
+ *
+ * @example
+ * <HeroSplit heading="Build faster" subheading="Launch confidently" />
+ */
+export function HeroSplit({
+  id,
+  className,
+  heading,
+  subheading,
+  section,
+  cta1,
+  cta2,
+  image = {
+    src: "/placeholders/gallery/hero-pexels-broken-9945014.avif",
+    alt: "Hero image",
+    className: "object-contain",
+  },
+  imageContainer,
+  textContainer = { className: "flex-1 p-5" },
+  buttonsContainer = { className: "flex flex-col md:flex-row gap-4 mt-6" },
+  textAlign = "center",
+  fallback,
+  ariaLabel = "Hero section",
+  enableMotion = true,
+  imageLayout = "full-bleed",
+}: HeroSplitProps) {
+  const lgTextAlignClasses = {
+    left: "lg:text-left",
+    right: "lg:text-right",
+    center: "lg:text-center",
+  } as const;
+  const lgItemsAlignClasses = {
+    left: "lg:items-start",
+    right: "lg:items-end",
+    center: "lg:items-center",
+  } as const;
+  const lgJustifyAlignClasses = {
+    left: "lg:justify-start",
+    right: "lg:justify-end",
+    center: "lg:justify-center",
+  } as const;
+  const buttonLift = enableMotion
+    ? "transition-all duration-200 hover:-translate-y-0.5"
+    : "transition-none hover:!translate-y-0";
+
+  // Defaults for text props (normalized below)
+  const defaultHeading = {
+    text: "Lorem ipsum dolor sit amet",
+    className: "text-3xl md:text-4xl font-bold leading-tight text-foreground",
+  };
+  const defaultSubheading = {
+    text: "Consectetur adipiscing elit, sed do eiusmod tempor.",
+    className: "text-lg md:text-xl text-foreground mt-4 mb-6",
+  };
+
+  const normalizedHeading =
+    typeof heading === "string"
+      ? { text: heading, className: defaultHeading.className }
+      : {
+          text: heading?.text ?? defaultHeading.text,
+          className: cn(defaultHeading.className, heading?.className),
+        };
+
+  const normalizedSubheading =
+    typeof subheading === "string"
+      ? { text: subheading, className: defaultSubheading.className }
+      : {
+          text: subheading?.text ?? defaultSubheading.text,
+          className: cn(defaultSubheading.className, subheading?.className),
+        };
+
+  // CTA defaults and normalization (merge, don't replace)
+  const defaultCta1 = {
+    label: "Get Started",
+    href: "#contact",
+    variant: "default" as const,
+    size: "default" as const,
+    className:
+      "shadow-lg hover:shadow-xl transition-all duration-200 hover:-translate-y-0.5",
+  };
+
+  const mergedCta1 = {
+    ...defaultCta1,
+    ...(cta1 ?? {}),
+    className: cn(defaultCta1.className, cta1?.className, buttonLift),
+  };
+
+  const defaultCta2 = {
+    label: "Learn More",
+    href: "#",
+    variant: "outline" as const,
+    size: "default" as const,
+    className: "",
+  };
+
+  const mergedCta2 = cta2
+    ? {
+        ...defaultCta2,
+        ...cta2,
+        className: cn(defaultCta2.className, cta2.className, buttonLift),
+      }
+    : undefined;
+
+  const defaultSectionPadded = cn(
+    "px-8 pt-8 pb-8 md:min-h-[60vh] lg:min-h-[70vh]",
+  );
+
+  const defaultSectionFull = cn(
+    "relative overflow-hidden pt-0 pb-0 md:min-h-[60vh] lg:min-h-[70vh]",
+  );
+
+  const defaultImageContainerPadded = cn(
+    "relative mb-4 h-48 min-h-[12rem] w-full md:mb-0 md:h-72 md:w-1/2",
+  );
+
+  // For full-bleed: absolute positioning on large screens to break out completely
+  const defaultImageContainerFull = cn(
+    "relative h-48 w-full md:absolute md:inset-y-0 md:right-0 md:h-full md:w-1/2",
+  );
+
+  const baseSectionClass =
+    imageLayout === "full-bleed" ? defaultSectionFull : defaultSectionPadded;
+
+  const finalSectionClass = cn(baseSectionClass, section?.className);
+
+  const baseImageContainerClass =
+    imageLayout === "full-bleed"
+      ? defaultImageContainerFull
+      : defaultImageContainerPadded;
+
+  const finalImageContainerClass = cn(
+    baseImageContainerClass,
+    imageContainer?.className,
+  );
+
+  // -- This overrides the image.className that is passed from importing components ... devs should be able to decide on cover/contain from the importing component.
+  const finalImageClass = cn(
+    image?.className,
+    imageLayout === "full-bleed"
+      ? "object-cover object-center md:object-right"
+      : "object-contain object-center",
+  );
+
+  return (
+    <section
+      id={id}
+      className={cn(finalSectionClass, className)}
+      aria-label={ariaLabel}
+    >
+      <div
+        className={cn(
+          "flex flex-col items-stretch",
+          imageLayout === "full-bleed"
+            ? "md:block"
+            : "md:flex-row md:items-start",
+        )}
+      >
+        {/* Text container - takes up left side on large screens */}
+        <div
+          className={cn(
+            "w-full",
+            imageLayout === "full-bleed" &&
+              "relative z-10 md:w-1/2 md:px-8 md:py-12",
+            textContainer.className,
+          )}
+        >
+          <div
+            className={cn(
+              "flex flex-col items-center",
+              lgItemsAlignClasses[textAlign],
+            )}
+          >
+            <h1
+              className={cn(
+                "text-center",
+                lgTextAlignClasses[textAlign],
+                normalizedHeading.className,
+              )}
+            >
+              {normalizedHeading.text}
+            </h1>
+
+            <p
+              className={cn(
+                "text-center",
+                lgTextAlignClasses[textAlign],
+                normalizedSubheading.className,
+              )}
+            >
+              {normalizedSubheading.text}
+            </p>
+
+            <div
+              className={cn(
+                "flex flex-col items-center justify-center gap-4 sm:flex-row",
+                lgJustifyAlignClasses[textAlign],
+                lgItemsAlignClasses[textAlign],
+                buttonsContainer.className,
+              )}
+            >
+              {mergedCta1.label && (
+                <Button
+                  asChild
+                  variant={mergedCta1.variant}
+                  size={mergedCta1.size}
+                  className={mergedCta1.className}
+                  unstyled={mergedCta1.unstyled}
+                  style={mergedCta1.style}
+                >
+                  <Link
+                    href={mergedCta1.href || "#"}
+                    aria-label={mergedCta1.label}
+                  >
+                    {mergedCta1.label}
+                  </Link>
+                </Button>
+              )}
+
+              {mergedCta2?.label && (
+                <Button
+                  asChild
+                  variant={mergedCta2.variant}
+                  size={mergedCta2.size}
+                  className={mergedCta2.className}
+                  unstyled={mergedCta2.unstyled}
+                  style={mergedCta2.style}
+                >
+                  <Link
+                    href={mergedCta2.href || "#"}
+                    aria-label={mergedCta2.label}
+                  >
+                    {mergedCta2.label}
+                  </Link>
+                </Button>
+              )}
+            </div>
+          </div>
+        </div>
+
+        {/* Image container - absolutely positioned on right side for full-bleed */}
+        <div className={cn(finalImageContainerClass)}>
+          {image?.src ? (
+            <Image
+              priority
+              fetchPriority="high"
+              src={image.src}
+              alt={image.alt || "Hero image"}
+              className={finalImageClass}
+              fill
+              sizes="(min-width: 768px) 50vw, 100vw"
+              quality={75}
+            />
+          ) : (
+            <div className="absolute inset-0">{fallback || null}</div>
+          )}
+        </div>
+      </div>
+    </section>
+  );
+}