@struq/skill 0.2.2 → 0.4.0

package/skills/struq/blocks/kit/MediaFrame.tsx

@@ -0,0 +1,96 @@
+"use client";
+// components/struq/MediaFrame.tsx (Struq recipe)
+// The only way an image goes on the page. It always holds a real image from lib/struq-images.ts
+// (written by scripts/images.mjs), so a frame can never ship empty.
+//
+// - reveal "scroll": the frame opens bottom-up like a curtain as it enters, the photo settles from 1.3x.
+// - reveal "load": the same curtain on mount, for the hero.
+// - parallax: the photo pans inside the frame while the frame scrolls past (scrubbed).
+//
+// <MediaFrame image={images.hero[0]} ratio="16/9" priority sizes="100vw" reveal="load" />
+// <MediaFrame image={images.card[2]} ratio="3/2" sizes="(min-width: 768px) 40vw, 100vw" />
+import Image from "next/image";
+import { useRef } from "react";
+import { gsap, useGSAP } from "./gsap";
+import type { StruqImage } from "./images";
+
+type Props = {
+  image: StruqImage;
+  /** CSS aspect ratio, for example "16/9", "3/2", "4/5", "1/1", "21/9". Defaults to the file's own. */
+  ratio?: string;
+  className?: string;
+  sizes?: string;
+  /** The page's one LCP image (the hero). Exactly one per page. */
+  priority?: boolean;
+  reveal?: "scroll" | "load" | "none";
+  parallax?: boolean;
+  /** Override the alt, for example a translation on a non-Dutch site. "" marks it decorative. */
+  alt?: string;
+};
+
+export function MediaFrame({
+  image,
+  ratio,
+  className = "",
+  sizes = "100vw",
+  priority = false,
+  reveal = "scroll",
+  parallax = true,
+  alt,
+}: Props) {
+  const frame = useRef<HTMLElement>(null);
+  const inner = useRef<HTMLDivElement>(null);
+
+  useGSAP(
+    () => {
+      const el = frame.current;
+      const photo = inner.current;
+      if (!el || !photo) return;
+      const mm = gsap.matchMedia();
+      mm.add("(prefers-reduced-motion: no-preference)", () => {
+        if (reveal !== "none") {
+          const trigger = reveal === "scroll" ? { trigger: el, start: "top 88%", once: true } : undefined;
+          gsap.fromTo(
+            el,
+            { clipPath: "inset(100% 0% 0% 0%)" },
+            { clipPath: "inset(0% 0% 0% 0%)", duration: 1.4, ease: "power4.inOut", delay: reveal === "load" ? 0.2 : 0, scrollTrigger: trigger },
+          );
+          gsap.fromTo(photo, { scale: 1.3 }, { scale: parallax ? 1.12 : 1, duration: 1.8, ease: "expo.out", delay: reveal === "load" ? 0.2 : 0, scrollTrigger: trigger });
+        }
+        if (parallax) {
+          gsap.fromTo(
+            photo,
+            { yPercent: -5 },
+            { yPercent: 5, ease: "none", scrollTrigger: { trigger: el, start: "top bottom", end: "bottom top", scrub: true } },
+          );
+        }
+      });
+      el.dataset.ready = "1";
+      return () => mm.revert();
+    },
+    { scope: frame },
+  );
+
+  return (
+    <figure
+      ref={frame}
+      data-frame={reveal === "none" ? "still" : "mask"}
+      className={`relative overflow-hidden bg-surface-2 ${className}`}
+      style={{ aspectRatio: ratio ?? `${image.width}/${image.height}` }}
+    >
+      <div ref={inner} className="absolute inset-0" style={{ scale: parallax ? "1.12" : undefined }}>
+        <Image
+          src={image.src}
+          alt={alt ?? image.alt}
+          fill
+          sizes={sizes}
+          // eager + high fetch priority works on every Next.js major ("priority" is deprecated in 16).
+          loading={priority ? "eager" : "lazy"}
+          fetchPriority={priority ? "high" : "auto"}
+          unoptimized={image.unoptimized}
+          className="object-cover"
+        />
+      </div>
+    </figure>
+  );
+}

package/skills/struq/blocks/kit/PinnedZoom.tsx

@@ -0,0 +1,89 @@
+"use client";
+// components/struq/PinnedZoom.tsx (Struq recipe): SHOWPIECE
+// The stage pins; a small framed photo opens to full bleed while the statement above it lifts
+// away and a closing line arrives over the photo. One scrubbed timeline, so it plays with the
+// scroll in both directions. Under reduced motion it is a still full-bleed photo with the text.
+//
+// <PinnedZoom
+//   image={images.band[0]}
+//   statement="Veertig plekken, één kaart."
+//   closing="Reserveer voor vanavond, of voor zaterdag."
+// />
+import Image from "next/image";
+import { useRef } from "react";
+import { gsap, useGSAP } from "./gsap";
+import type { StruqImage } from "./images";
+
+type Props = {
+  image: StruqImage;
+  statement: string;
+  closing?: string;
+  className?: string;
+};
+
+export function PinnedZoom({ image, statement, closing, className = "" }: Props) {
+  const stage = useRef<HTMLElement>(null);
+
+  useGSAP(
+    () => {
+      const el = stage.current;
+      if (!el) return;
+      const q = gsap.utils.selector(el);
+      const mm = gsap.matchMedia();
+      mm.add("(prefers-reduced-motion: no-preference)", () => {
+        // Two numbers drive the clip, never a tweened string: the browser shortens a symmetric inset to two
+        // values, GSAP pairs them with four end values, and two edges jump open in one frame.
+        const frame = q("[data-zoom-frame]")[0] as HTMLElement;
+        const clip = { y: 22, x: 30 };
+        const paint = () => {
+          frame.style.clipPath = `inset(${clip.y}% ${clip.x}% ${clip.y}% ${clip.x}%)`;
+        };
+        paint();
+        gsap.set(q("[data-zoom-closing]"), { autoAlpha: 0, yPercent: 40 });
+        const tl = gsap.timeline({
+          defaults: { ease: "none" },
+          scrollTrigger: { trigger: el, start: "top top", end: "+=160%", pin: true, scrub: 1 },
+        });
+        tl.to(clip, { y: 0, x: 0, duration: 1, onUpdate: paint }, 0)
+          .fromTo(q("[data-zoom-photo]"), { scale: 1.35 }, { scale: 1, duration: 1 }, 0)
+          .to(q("[data-zoom-statement]"), { yPercent: -60, autoAlpha: 0, duration: 0.45 }, 0)
+          .to(q("[data-zoom-closing]"), { yPercent: 0, autoAlpha: 1, duration: 0.35 }, 0.62);
+        return () => {
+          frame.style.clipPath = "";
+        };
+      });
+      // Still version: the photo is full bleed from the start, so the statement turns light.
+      mm.add("(prefers-reduced-motion: reduce)", () => {
+        gsap.set(q("[data-zoom-statement]"), { color: "var(--on-photo)" });
+      });
+      return () => mm.revert();
+    },
+    { scope: stage },
+  );
+
+  return (
+    <section ref={stage} className={`relative h-svh overflow-hidden bg-surface-0 ${className}`}>
+      <div data-zoom-frame="" className="absolute inset-0 overflow-hidden">
+        <div data-zoom-photo="" className="absolute inset-0">
+          <Image src={image.src} alt={image.alt} fill sizes="100vw" unoptimized={image.unoptimized} className="object-cover" />
+        </div>
+        {/* A flat black scrim, so the closing line reads on any photo, on light and dark palettes. */}
+        <div aria-hidden className="absolute inset-0 bg-black opacity-35" />
+      </div>
+      <p
+        data-zoom-statement=""
+        className="font-display text-h2 absolute inset-x-6 top-[9vh] mx-auto max-w-[22ch] text-center text-ink md:inset-x-[8vw]"
+      >
+        {statement}
+      </p>
+      {closing ? (
+        <p
+          data-zoom-closing=""
+          className="font-display text-h2 absolute inset-x-6 bottom-[12vh] max-w-[20ch] text-on-photo md:left-[8vw]"
+        >
+          {closing}
+        </p>
+      ) : null}
+    </section>
+  );
+}

package/skills/struq/blocks/kit/Reveal.tsx

@@ -0,0 +1,64 @@
+"use client";
+// components/struq/Reveal.tsx (Struq recipe)
+// Staggered rise for a group of text blocks: every direct child rises 48px from a fade as the
+// group scrolls into view. Opacity AND transform, never opacity alone, expo.out, fired once.
+//
+// <Reveal className="grid gap-6">
+//   <h2 className="text-h2">...</h2>
+//   <p className="text-lead">...</p>
+// </Reveal>
+//
+// Before hydration the children are hidden only when JavaScript runs (the `js` class from the
+// layout), and a CSS failsafe shows them after 3s if hydration never comes (globals.css).
+import { useRef } from "react";
+import { gsap, useGSAP } from "./gsap";
+
+type Props = {
+  children: React.ReactNode;
+  className?: string;
+  as?: "div" | "section" | "header" | "footer" | "ul" | "ol";
+  /** Distance each child rises, in px. 24 to 80. */
+  y?: number;
+  stagger?: number;
+  delay?: number;
+  /** "scroll" waits for the viewport; "load" plays on mount (for the hero). */
+  on?: "scroll" | "load";
+};
+
+export function Reveal({ children, className = "", as = "div", y = 48, stagger = 0.08, delay = 0, on = "scroll" }: Props) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  useGSAP(
+    () => {
+      const el = ref.current;
+      if (!el) return;
+      const items = Array.from(el.children);
+      const mm = gsap.matchMedia();
+      mm.add(
+        { motion: "(prefers-reduced-motion: no-preference)", reduce: "(prefers-reduced-motion: reduce)" },
+        (ctx) => {
+          const reduce = ctx.conditions?.reduce;
+          gsap.from(items, {
+            y: reduce ? 0 : y,
+            autoAlpha: 0,
+            duration: reduce ? 0.5 : 0.9,
+            ease: "expo.out",
+            stagger,
+            delay,
+            scrollTrigger: on === "scroll" ? { trigger: el, start: "top 85%", once: true } : undefined,
+          });
+        },
+      );
+      el.dataset.ready = "1";
+      return () => mm.revert();
+    },
+    { scope: ref },
+  );
+
+  const Tag = as as "div";
+  return (
+    <Tag ref={ref} data-reveal="" className={className}>
+      {children}
+    </Tag>
+  );
+}

package/skills/struq/blocks/kit/SmoothScroll.tsx

@@ -0,0 +1,57 @@
+"use client";
+// components/struq/SmoothScroll.tsx (Struq recipe)
+// Lenis smooth scroll on the GSAP ticker: one requestAnimationFrame for the whole page.
+// Mount it once, in app/layout.tsx, around {children}.
+//
+// Why it is built this way:
+// - autoRaf false plus gsap.ticker: Lenis and ScrollTrigger sample scroll on the same frame,
+//   so scrubbed timelines never micro-stutter.
+// - lagSmoothing(0): GSAP never "catches up" after a long frame, which would jump scrubs.
+// - Lenis is created inside the effect, so there is no ref race that can leave the wheel dead.
+// - Reduced motion: no Lenis, native scroll. ScrollTrigger keeps working on native scroll.
+import Lenis from "lenis";
+import "lenis/dist/lenis.css";
+import { useEffect } from "react";
+import { gsap, ScrollTrigger } from "./gsap";
+
+let current: Lenis | null = null;
+
+/**
+ * The page's Lenis instance, or null under reduced motion and before mount.
+ * An overlay menu calls getLenis()?.stop() when it opens and getLenis()?.start() on EVERY close path.
+ */
+export function getLenis() {
+  return current;
+}
+
+export function SmoothScroll({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    ScrollTrigger.config({ ignoreMobileResize: true });
+    const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+    // Fonts change line breaks and section heights: re-measure every trigger once they land.
+    const refresh = () => ScrollTrigger.refresh();
+    document.fonts?.ready.then(refresh);
+    const late = window.setTimeout(refresh, 600);
+
+    if (reduce) {
+      return () => window.clearTimeout(late);
+    }
+
+    const lenis = new Lenis({ lerp: 0.1, autoRaf: false, anchors: true });
+    const raf = (time: number) => lenis.raf(time * 1000); // GSAP gives seconds, Lenis wants ms
+    lenis.on("scroll", ScrollTrigger.update);
+    gsap.ticker.add(raf);
+    gsap.ticker.lagSmoothing(0);
+    current = lenis;
+
+    return () => {
+      window.clearTimeout(late);
+      gsap.ticker.remove(raf);
+      lenis.destroy();
+      current = null;
+    };
+  }, []);
+
+  return <>{children}</>;
+}

package/skills/struq/blocks/kit/SplitHeadline.tsx

@@ -0,0 +1,68 @@
+"use client";
+// components/struq/SplitHeadline.tsx (Struq recipe)
+// The hero headline: SplitText cuts it into lines, each line rises out of its own mask.
+// autoSplit re-cuts it when the width or the webfont changes, so mobile line breaks stay right.
+//
+// <SplitHeadline as="h1" className="font-display text-display max-w-[14ch]">
+//   Vis en groente, van het seizoen.
+// </SplitHeadline>
+//
+// Pass plain text (or text with <em>): SplitText needs text nodes, not components.
+import { useRef } from "react";
+import { gsap, SplitText, useGSAP } from "./gsap";
+
+type Props = {
+  children: React.ReactNode;
+  as?: "h1" | "h2" | "h3" | "p";
+  className?: string;
+  /** "load" for the hero, "scroll" for a statement further down. */
+  on?: "load" | "scroll";
+  delay?: number;
+  /** Mark it as copy the hero canvas hushes behind. On by default for the h1. */
+  quiet?: boolean;
+};
+
+export function SplitHeadline({ children, as = "h1", className = "", on = "load", delay = 0.15, quiet = as === "h1" }: Props) {
+  const ref = useRef<HTMLHeadingElement>(null);
+
+  useGSAP(
+    () => {
+      const el = ref.current;
+      if (!el) return;
+      const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+      if (reduce) {
+        el.dataset.ready = "1";
+        gsap.from(el, { autoAlpha: 0, duration: 0.6 });
+        return;
+      }
+
+      const split = SplitText.create(el, {
+        type: "lines",
+        mask: "lines",
+        linesClass: "struq-line",
+        autoSplit: true,
+        onSplit(self) {
+          return gsap.from(self.lines, {
+            yPercent: 115,
+            duration: 1.25,
+            ease: "expo.out",
+            stagger: 0.09,
+            delay,
+            scrollTrigger: on === "scroll" ? { trigger: el, start: "top 80%", once: true } : undefined,
+          });
+        },
+      });
+      el.dataset.ready = "1";
+      return () => split.revert();
+    },
+    { scope: ref },
+  );
+
+  const Tag = as as "h1";
+  return (
+    <Tag ref={ref} data-split="" data-quiet={quiet ? "" : undefined} className={className}>
+      {children}
+    </Tag>
+  );
+}