Merge pull request #58 from pras75299/chore/backlog-phase-8-meta-version

Chore/backlog phase 8 meta version

Author: pras75299

CLAUDE.md

@@ -177,9 +177,10 @@ Three config files drive the entire docs site:
 2. Add entry to `registry/config.ts` (name, dependencies, files array, optional `tailwindConfig` for custom keyframes)
 3. Add docs metadata to `registry/docs.json`
 4. Add demo to `apps/www/config/demos.tsx` (`componentDemos`)
-5. Run `pnpm build:registry` from root to regenerate `registry.json`, refresh `apps/www/public/registry/*` and **`apps/www/public/r/*`**, sync `apps/www/components/ui/{component-name}.tsx`, and generate `apps/www/config/components.ts` plus `apps/www/config/docs-scenarios.ts`
+5. Add an entry to `registry/changelogs.json` under the new slug — at minimum `[{ "version": "1.0.0", "date": "YYYY-MM-DD", "changes": ["Initial release."] }]`. The build script reads `entries[0]` as the component's `meta.version`; entries must be newest-first (descending semver).
+6. Run `pnpm build:registry` from root to regenerate `registry.json`, refresh `apps/www/public/registry/*` and **`apps/www/public/r/*`**, sync `apps/www/components/ui/{component-name}.tsx`, and generate `apps/www/config/components.ts` plus `apps/www/config/docs-scenarios.ts`
 
-When editing an existing component, update `registry/{component}/component.tsx` and then run `pnpm build:registry` to refresh the generated docs copies and registry artifacts.
+When editing an existing component, update `registry/{component}/component.tsx` and — if the change is user-visible — prepend a new entry to that slug's array in `registry/changelogs.json` with a bumped semver. Then run `pnpm build:registry` to refresh the generated docs copies and registry artifacts.
 
 ## Component Design Rules
 

apps/www/app/blocks/[slug]/page.tsx

@@ -108,11 +108,17 @@ export default async function BlockPage(props: { params: Promise<{ slug: string
       {docs?.scenarios?.length ? (
         <section className="mb-12 space-y-6 border-t border-neutral-200 pt-8 dark:border-neutral-800">
           <h2 className="text-xl font-semibold text-neutral-900 dark:text-white">Scenarios</h2>
-          <div className="space-y-8">
+          <div className="space-y-10">
             {docs.scenarios.map((s, i) => (
               <article key={s.title} className="space-y-3">
                 <h3 className="text-base font-medium text-neutral-900 dark:text-white">{s.title}</h3>
                 <p className="text-sm text-neutral-600 dark:text-neutral-400">{s.description}</p>
+                {s.demoKey ? (
+                  // Lazy-mount: /blocks slug pages stack multiple full-height
+                  // hero demos. Without IO gating, every off-screen scenario
+                  // would run RAF / pointer listeners at once.
+                  <ComponentPreview slug={s.demoKey} variant="block" lazy />
+                ) : null}
                 <div className="group relative overflow-hidden rounded-lg border border-neutral-200 bg-neutral-50 dark:border-neutral-800 dark:bg-neutral-950">
                   <div
                     className="overflow-x-auto p-4 text-sm font-mono [&>pre]:!bg-transparent [&>pre]:!p-0"

apps/www/app/blocks/page.tsx

@@ -1,19 +1,56 @@
 "use client";
 
 import Link from "next/link";
-import { useMemo, useState } from "react";
+import { useMemo, useRef, useState } from "react";
 import { motion } from "motion/react";
 import { ArrowRight, Blocks as BlocksIcon } from "lucide-react";
 import { componentsList, isNewComponent } from "@/config/components";
 import { useTheme } from "@/contexts/theme-context";
 import { useIsClient } from "@/lib/use-is-client";
 import { cn } from "@/lib/utils";
+import { BLOCK_THUMBNAIL_SLUG } from "@/config/block-thumbnail-slugs";
 import ComponentPreview from "@/components/component-preview";
 
 const blocksList = componentsList.filter((c) => c.kind === "block");
 
 const ALL = "All";
 
+function BlockCardThumbnail({
+  slug,
+  isDark,
+}: {
+  slug: string;
+  isDark: boolean;
+}) {
+  const frameRef = useRef<HTMLDivElement>(null);
+  return (
+    <div
+      ref={frameRef}
+      className={cn(
+        "relative aspect-[16/10] overflow-hidden",
+        isDark ? "bg-neutral-950" : "bg-neutral-100",
+      )}
+    >
+      <div className="pointer-events-none absolute left-1/2 top-1/2 h-[100svh] w-[240%] max-w-none -translate-x-1/2 -translate-y-1/2 origin-center scale-[0.4] sm:scale-[0.48]">
+        <ComponentPreview
+          slug={slug}
+          lazy
+          lazyRoot={frameRef}
+          variant="thumbnail"
+        />
+      </div>
+      <div
+        className={cn(
+          "pointer-events-none absolute inset-0",
+          isDark
+            ? "bg-gradient-to-t from-black/40 via-transparent to-transparent"
+            : "bg-gradient-to-t from-white/30 via-transparent to-transparent",
+        )}
+      />
+    </div>
+  );
+}
+
 const cardVariants = {
   hidden: { opacity: 0, y: 18, scale: 0.97 },
   visible: (i: number) => ({
@@ -177,27 +214,10 @@ export default function BlocksIndex() {
                         : "border-neutral-200 bg-white hover:border-neutral-300 hover:shadow-lg",
                     )}
                   >
-                    <div
-                      className={cn(
-                        "relative aspect-[16/10] overflow-hidden",
-                        isDark ? "bg-neutral-950" : "bg-neutral-100",
-                      )}
-                    >
-                      <div
-                        className="pointer-events-none absolute inset-0 origin-top-left scale-[0.45] sm:scale-[0.55]"
-                        style={{ width: "182%", height: "222%" }}
-                      >
-                        <ComponentPreview slug={block.slug} lazy />
-                      </div>
-                      <div
-                        className={cn(
-                          "pointer-events-none absolute inset-0",
-                          isDark
-                            ? "bg-gradient-to-t from-black/40 via-transparent to-transparent"
-                            : "bg-gradient-to-t from-white/30 via-transparent to-transparent",
-                        )}
-                      />
-                    </div>
+                    <BlockCardThumbnail
+                      slug={BLOCK_THUMBNAIL_SLUG[block.slug] ?? block.slug}
+                      isDark={isDark}
+                    />
                     <div className="flex items-start justify-between gap-3 p-4">
                       <div className="min-w-0">
                         <div className="flex items-center gap-2">

apps/www/components/component-preview.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { forwardRef, useRef, type ForwardedRef } from "react";
+import { forwardRef, useRef, type ForwardedRef, type RefObject } from "react";
 import { motion, useInView } from "motion/react";
 import { componentDemos } from "@/config/demos";
 import { useTheme } from "@/contexts/theme-context";
@@ -11,7 +11,8 @@ type ComponentPreviewProps = {
   /** Extra class names merged on the root motion.div via `cn` (consumer style overrides). */
   className?: string;
   /** "block" suppresses the grid backdrop and uses a full-hero min-height. */
-  variant?: "default" | "block";
+  /** "thumbnail" — `/blocks` index cards: full hero height, content optically centered in crop. */
+  variant?: "default" | "block" | "thumbnail";
   /**
    * When true, the inner demo only mounts while the preview is near or inside
    * the viewport. Used by `/blocks` to keep dozens of motion timelines / RAF
@@ -23,6 +24,12 @@ type ComponentPreviewProps = {
    * benefit from observing them.
    */
   lazy?: boolean;
+  /**
+   * When `lazy` is set, observe this root for intersection (e.g. the card
+   * frame). Avoids missed mounts when the preview sits inside a transformed
+   * scale wrapper on `/blocks`.
+   */
+  lazyRoot?: RefObject<Element | null>;
 };
 
 export default function ComponentPreview(props: ComponentPreviewProps) {
@@ -33,11 +40,14 @@ function EagerPreview(props: ComponentPreviewProps) {
   return <PreviewShell {...props} shouldRender />;
 }
 
-function LazyPreview(props: ComponentPreviewProps) {
+function LazyPreview({ lazyRoot, ...props }: ComponentPreviewProps) {
   const cardRef = useRef<HTMLDivElement>(null);
   // `once: false` → demo unmounts on exit, freeing RAF / pointer listeners.
   // 200px above + below the viewport warms the demo before scroll reaches it.
-  const isInView = useInView(cardRef, { once: false, margin: "200px 0px" });
+  const isInView = useInView(lazyRoot ?? cardRef, {
+    once: false,
+    margin: "200px 0px",
+  });
   return <PreviewShell {...props} shouldRender={isInView} ref={cardRef} />;
 }
 
@@ -60,38 +70,47 @@ const PreviewShell = forwardRef<HTMLDivElement, PreviewShellProps>(function Prev
 
   const isDark = theme === "dark";
   const isBlock = variant === "block";
+  const isThumbnail = variant === "thumbnail";
+  const isHeroFrame = isBlock || isThumbnail;
   const hasOverflowHidden =
-    isBlock || (slug !== "horizontal-scroll-gallery" && slug !== "outlined-mega-mark");
-  const isOutlinedMegaMark = !isBlock && slug === "outlined-mega-mark";
+    isHeroFrame || (slug !== "horizontal-scroll-gallery" && slug !== "outlined-mega-mark");
+  const isOutlinedMegaMark = !isHeroFrame && slug === "outlined-mega-mark";
 
   return (
     <motion.div
       ref={ref}
       className={cn(
         "w-full rounded-xl border relative flex",
-        isBlock
-          ? "min-h-[70svh] items-stretch"
-          : isOutlinedMegaMark
-            ? "min-h-[min(32rem,82dvh)] flex-col items-stretch py-4 sm:py-6"
-            : "min-h-[300px] items-center justify-center",
+        isThumbnail
+          ? "min-h-[100svh] items-center justify-center"
+          : isBlock
+            ? "min-h-[70svh] items-stretch"
+            : isOutlinedMegaMark
+              ? "min-h-[min(32rem,82dvh)] flex-col items-stretch py-4 sm:py-6"
+              : "min-h-[300px] items-center justify-center",
         hasOverflowHidden && "overflow-hidden",
+        isThumbnail && "rounded-none border-0",
         isDark ? "border-neutral-800 bg-neutral-950/50" : "border-neutral-200 bg-neutral-50/80",
         className,
       )}
       initial={false}
       animate={{
-        backgroundColor: isBlock
+        backgroundColor: isHeroFrame
           ? isDark
             ? "rgb(10,10,10)"
             : "rgb(255,255,255)"
           : isDark
             ? "rgba(10,10,10,0.5)"
             : "rgba(250,250,250,0.8)",
-        borderColor: isDark ? "rgb(38,38,38)" : "rgb(229,229,229)",
+        borderColor: isThumbnail
+          ? "transparent"
+          : isDark
+            ? "rgb(38,38,38)"
+            : "rgb(229,229,229)",
       }}
       transition={{ type: "spring", stiffness: 300, damping: 30 }}
     >
-      {!isBlock && (
+      {!isHeroFrame && (
         <div
           className={cn(
             "absolute inset-0 z-0 opacity-20 pointer-events-none [background-size:24px_24px]",
@@ -112,7 +131,11 @@ const PreviewShell = forwardRef<HTMLDivElement, PreviewShellProps>(function Prev
         {shouldRender ? (
           <Demo theme={theme} />
         ) : (
-          <LazyPlaceholder isBlock={isBlock} isOutlinedMegaMark={isOutlinedMegaMark} />
+          <LazyPlaceholder
+            isBlock={isBlock}
+            isThumbnail={isThumbnail}
+            isOutlinedMegaMark={isOutlinedMegaMark}
+          />
         )}
       </div>
     </motion.div>
@@ -126,21 +149,25 @@ const PreviewShell = forwardRef<HTMLDivElement, PreviewShellProps>(function Prev
  */
 function LazyPlaceholder({
   isBlock,
+  isThumbnail,
   isOutlinedMegaMark,
 }: {
   isBlock: boolean;
+  isThumbnail: boolean;
   isOutlinedMegaMark: boolean;
 }) {
   return (
     <div
       aria-hidden
       className={cn(
         "h-full w-full",
-        isBlock
-          ? "min-h-[70svh]"
-          : isOutlinedMegaMark
-            ? "min-h-[min(32rem,82dvh)]"
-            : "min-h-[300px]",
+        isThumbnail
+          ? "min-h-[100svh]"
+          : isBlock
+            ? "min-h-[70svh]"
+            : isOutlinedMegaMark
+              ? "min-h-[min(32rem,82dvh)]"
+              : "min-h-[300px]",
       )}
     />
   );

apps/www/components/ui/hero-iridescent-sweep.tsx

@@ -4,6 +4,15 @@ import { useId, type ComponentProps, type ReactNode } from "react";
 import { motion, useReducedMotion } from "motion/react";
 import { cn } from "@/lib/utils";
 
+const DEFAULT_FOIL_PALETTE = [
+  "#ff9bd1",
+  "#ffd66b",
+  "#9bffd6",
+  "#6bb5ff",
+  "#c89bff",
+  "#ff9bd1",
+] as const;
+
 type IridescentSweepBackgroundProps = {
   className?: string;
   /** Conic-gradient rotation cycle in seconds. */
@@ -12,25 +21,35 @@ type IridescentSweepBackgroundProps = {
   hue?: number;
   /** Grain intensity 0–1. */
   grain?: number;
+  /** Section / vignette base (e.g. `#0e0a14`). */
+  baseColor?: string;
+  /** Holographic foil stops for the rotating conic gradient. */
+  palette?: ReadonlyArray<string>;
 };
 
 export function IridescentSweepBackground({
   className,
   speed = 22,
   hue = 0,
   grain = 0.35,
+  baseColor = "#0e0a14",
+  palette = DEFAULT_FOIL_PALETTE,
 }: IridescentSweepBackgroundProps) {
   const reduced = useReducedMotion();
   // Clamp speed defensively — negative or non-finite values would yield invalid durations.
   const safeSpeed = Number.isFinite(speed) && speed > 0 ? speed : 0;
   const cycle = reduced ? 0 : safeSpeed;
   const filterId = useId();
+  // Default-only fires on undefined; treat an explicit empty array as "no
+  // palette" so `palette.join(", ")` can't produce an invalid `conic-gradient(...)`.
+  const resolvedPalette =
+    palette && palette.length > 0 ? palette : DEFAULT_FOIL_PALETTE;
 
   return (
     <div
       aria-hidden
-      className={cn("absolute inset-0 overflow-hidden bg-[#0e0a14]", className)}
-      style={{ filter: `hue-rotate(${hue}deg)` }}
+      className={cn("absolute inset-0 overflow-hidden", className)}
+      style={{ backgroundColor: baseColor, filter: `hue-rotate(${hue}deg)` }}
     >
       <svg className="absolute -z-10 h-0 w-0" aria-hidden>
         <filter id={filterId}>
@@ -42,8 +61,7 @@ export function IridescentSweepBackground({
       <motion.div
         className="absolute inset-[-20%]"
         style={{
-          background:
-            "conic-gradient(from 0deg at 50% 50%, #ff9bd1, #ffd66b, #9bffd6, #6bb5ff, #c89bff, #ff9bd1)",
+          background: `conic-gradient(from 0deg at 50% 50%, ${resolvedPalette.join(", ")})`,
           filter: "blur(60px) saturate(1.4)",
           mixBlendMode: "screen",
           opacity: 0.85,
@@ -63,7 +81,12 @@ export function IridescentSweepBackground({
         animate={cycle ? { x: "60%" } : { x: "0%" }}
         transition={cycle ? { duration: 6, ease: "easeInOut", repeat: Infinity, repeatDelay: 1.4 } : undefined}
       />
-      <div className="absolute inset-0 bg-[radial-gradient(ellipse_at_center,_transparent_30%,_#0e0a14_92%)]" />
+      <div
+        className="absolute inset-0"
+        style={{
+          background: `radial-gradient(ellipse at center, transparent 30%, ${baseColor} 92%)`,
+        }}
+      />
       <div
         className="pointer-events-none absolute inset-0 mix-blend-overlay"
         style={{ filter: `url(#${filterId})`, opacity: grain }}