@snowcone-app/ui 0.1.43 → 0.2.0

package/src/primitives/ProgressiveBlur.tsx

@@ -0,0 +1,295 @@
+"use client";
+
+/**
+ * ProgressiveBlur - Layered backdrop-filter blur effect
+ *
+ * Creates a smooth progressive blur using multiple stacked layers with
+ * increasing blur values. Perfect for sticky headers, footers, or any
+ * UI element where content should gracefully blur as it scrolls underneath.
+ *
+ * @example
+ * // In a sticky header - blur content scrolling up from below
+ * <header className="sticky top-0">
+ *   <nav>...</nav>
+ *   <ProgressiveBlur position="bottom" height="40px" />
+ * </header>
+ *
+ * @example
+ * // At bottom of viewport - blur content scrolling down
+ * <ProgressiveBlur position="top" height="60px" />
+ */
+
+import React from "react";
+
+function cn(...classes: (string | undefined | null | false)[]) {
+  return classes.filter(Boolean).join(" ");
+}
+
+export interface ProgressiveBlurProps {
+  /** Additional CSS classes */
+  className?: string;
+  /** Height of the blur zone */
+  height?: string;
+  /** Position of the blur effect */
+  position?: "top" | "bottom" | "both";
+  /** Custom blur levels (default: exponential scale from 0.5px to 64px) */
+  blurLevels?: number[];
+  children?: React.ReactNode;
+}
+
+/**
+ * ProgressiveBlur creates a layered blur effect using multiple stacked divs
+ * with increasing backdrop-filter blur values and gradient masks.
+ *
+ * The default blur levels [0.5, 1, 2, 4, 8, 16, 32, 64] create an exponential
+ * progression that looks smooth and natural.
+ */
+export function ProgressiveBlur({
+  className,
+  height = "30%",
+  position = "bottom",
+  blurLevels = [0.5, 1, 2, 4, 8, 16, 32, 64],
+}: ProgressiveBlurProps) {
+  // Create array with length equal to blurLevels.length - 2 (for before/after pseudo elements)
+  const divElements = Array(blurLevels.length - 2).fill(null);
+
+  return (
+    <div
+      className={cn(
+        "gradient-blur pointer-events-none absolute inset-x-0 z-10",
+        className,
+        position === "top"
+          ? "top-0"
+          : position === "bottom"
+            ? "bottom-0"
+            : "inset-y-0"
+      )}
+      style={{
+        height: position === "both" ? "100%" : height,
+      }}
+    >
+      {/* First blur layer (pseudo element) */}
+      <div
+        className="absolute inset-0"
+        style={{
+          zIndex: 1,
+          backdropFilter: `blur(${blurLevels[0]}px)`,
+          WebkitBackdropFilter: `blur(${blurLevels[0]}px)`,
+          maskImage:
+            position === "bottom"
+              ? `linear-gradient(to bottom, rgba(0,0,0,0) 0%, rgba(0,0,0,1) 12.5%, rgba(0,0,0,1) 25%, rgba(0,0,0,0) 37.5%)`
+              : position === "top"
+                ? `linear-gradient(to top, rgba(0,0,0,0) 0%, rgba(0,0,0,1) 12.5%, rgba(0,0,0,1) 25%, rgba(0,0,0,0) 37.5%)`
+                : `linear-gradient(rgba(0,0,0,0) 0%, rgba(0,0,0,1) 5%, rgba(0,0,0,1) 95%, rgba(0,0,0,0) 100%)`,
+          WebkitMaskImage:
+            position === "bottom"
+              ? `linear-gradient(to bottom, rgba(0,0,0,0) 0%, rgba(0,0,0,1) 12.5%, rgba(0,0,0,1) 25%, rgba(0,0,0,0) 37.5%)`
+              : position === "top"
+                ? `linear-gradient(to top, rgba(0,0,0,0) 0%, rgba(0,0,0,1) 12.5%, rgba(0,0,0,1) 25%, rgba(0,0,0,0) 37.5%)`
+                : `linear-gradient(rgba(0,0,0,0) 0%, rgba(0,0,0,1) 5%, rgba(0,0,0,1) 95%, rgba(0,0,0,0) 100%)`,
+        }}
+      />
+
+      {/* Middle blur layers */}
+      {divElements.map((_, index) => {
+        const blurIndex = index + 1;
+        const startPercent = blurIndex * 12.5;
+        const midPercent = (blurIndex + 1) * 12.5;
+        const endPercent = (blurIndex + 2) * 12.5;
+
+        const maskGradient =
+          position === "bottom"
+            ? `linear-gradient(to bottom, rgba(0,0,0,0) ${startPercent}%, rgba(0,0,0,1) ${midPercent}%, rgba(0,0,0,1) ${endPercent}%, rgba(0,0,0,0) ${endPercent + 12.5}%)`
+            : position === "top"
+              ? `linear-gradient(to top, rgba(0,0,0,0) ${startPercent}%, rgba(0,0,0,1) ${midPercent}%, rgba(0,0,0,1) ${endPercent}%, rgba(0,0,0,0) ${endPercent + 12.5}%)`
+              : `linear-gradient(rgba(0,0,0,0) 0%, rgba(0,0,0,1) 5%, rgba(0,0,0,1) 95%, rgba(0,0,0,0) 100%)`;
+
+        return (
+          <div
+            key={`blur-${index}`}
+            className="absolute inset-0"
+            style={{
+              zIndex: index + 2,
+              backdropFilter: `blur(${blurLevels[blurIndex]}px)`,
+              WebkitBackdropFilter: `blur(${blurLevels[blurIndex]}px)`,
+              maskImage: maskGradient,
+              WebkitMaskImage: maskGradient,
+            }}
+          />
+        );
+      })}
+
+      {/* Last blur layer (pseudo element) */}
+      <div
+        className="absolute inset-0"
+        style={{
+          zIndex: blurLevels.length,
+          backdropFilter: `blur(${blurLevels[blurLevels.length - 1]}px)`,
+          WebkitBackdropFilter: `blur(${blurLevels[blurLevels.length - 1]}px)`,
+          maskImage:
+            position === "bottom"
+              ? `linear-gradient(to bottom, rgba(0,0,0,0) 87.5%, rgba(0,0,0,1) 100%)`
+              : position === "top"
+                ? `linear-gradient(to top, rgba(0,0,0,0) 87.5%, rgba(0,0,0,1) 100%)`
+                : `linear-gradient(rgba(0,0,0,0) 0%, rgba(0,0,0,1) 5%, rgba(0,0,0,1) 95%, rgba(0,0,0,0) 100%)`,
+          WebkitMaskImage:
+            position === "bottom"
+              ? `linear-gradient(to bottom, rgba(0,0,0,0) 87.5%, rgba(0,0,0,1) 100%)`
+              : position === "top"
+                ? `linear-gradient(to top, rgba(0,0,0,0) 87.5%, rgba(0,0,0,1) 100%)`
+                : `linear-gradient(rgba(0,0,0,0) 0%, rgba(0,0,0,1) 5%, rgba(0,0,0,1) 95%, rgba(0,0,0,0) 100%)`,
+        }}
+      />
+    </div>
+  );
+}
+
+// ============================================================================
+// Horizontal Blur Variants
+// ============================================================================
+
+export interface HorizontalProgressiveBlurProps {
+  /** Width of the blur zone in pixels */
+  width: number;
+  /** Additional CSS classes */
+  className?: string;
+  /** Custom blur levels (default: smooth transition for bidirectional effect) */
+  blurLevels?: number[];
+}
+
+/**
+ * HorizontalProgressiveBlur - Creates a bidirectional horizontal progressive blur effect.
+ *
+ * Blurs from both edges toward the center, creating maximum blur at the center (the seam)
+ * and fading to clear on both the left and right sides. Perfect for seamless image transitions.
+ *
+ * @example
+ * ```tsx
+ * // Center seam blur between two images
+ * <div className="relative">
+ *   <img src="/left.jpg" />
+ *   <HorizontalProgressiveBlur width={100} className="left-1/2 -translate-x-1/2" />
+ *   <img src="/right.jpg" />
+ * </div>
+ * ```
+ */
+export function HorizontalProgressiveBlur({
+  width,
+  className = "",
+  blurLevels = [0.25, 0.5, 1, 1.5, 2, 3, 4, 6, 9, 13, 18, 24],
+}: HorizontalProgressiveBlurProps) {
+  const numLayers = blurLevels.length;
+
+  return (
+    <div
+      className={cn(
+        "absolute top-0 bottom-0 pointer-events-none",
+        className
+      )}
+      style={{ width }}
+    >
+      {blurLevels.map((blur, index) => {
+        // Bidirectional: blur increases from edges (0%, 100%) toward center (50%)
+        // Each layer covers a band that gets narrower as blur increases
+        const layerRatio = index / (numLayers - 1); // 0 to 1
+        const bandStart = layerRatio * 47; // 0% to 47%
+        const bandEnd = 100 - bandStart; // 100% to 53%
+
+        // Smoother gradient transitions
+        const fadeWidth = 3;
+        const maskGradient = `linear-gradient(to right,
+          rgba(0,0,0,0) 0%,
+          rgba(0,0,0,0) ${Math.max(0, bandStart - fadeWidth)}%,
+          rgba(0,0,0,1) ${bandStart + fadeWidth}%,
+          rgba(0,0,0,1) ${bandEnd - fadeWidth}%,
+          rgba(0,0,0,0) ${Math.min(100, bandEnd + fadeWidth)}%,
+          rgba(0,0,0,0) 100%
+        )`;
+
+        return (
+          <div
+            key={`blur-layer-${index}`}
+            className="absolute inset-0"
+            style={{
+              zIndex: index + 1,
+              backdropFilter: `blur(${blur}px)`,
+              WebkitBackdropFilter: `blur(${blur}px)`,
+              maskImage: maskGradient,
+              WebkitMaskImage: maskGradient,
+            }}
+          />
+        );
+      })}
+    </div>
+  );
+}
+
+export interface RightToLeftProgressiveBlurProps {
+  /** Width of the blur zone in pixels */
+  width: number;
+  /** Additional CSS classes */
+  className?: string;
+  /** Custom blur levels (default: exponential increase for unidirectional effect) */
+  blurLevels?: number[];
+}
+
+/**
+ * RightToLeftProgressiveBlur - Creates a unidirectional progressive blur effect.
+ *
+ * Blur increases from right (clear) to left (max blur). Anchored to the right edge,
+ * blur builds up toward the left. Useful for fading content into a blurred edge.
+ *
+ * @example
+ * ```tsx
+ * // Blur left edge of content
+ * <div className="relative">
+ *   <RightToLeftProgressiveBlur width={80} className="left-0" />
+ *   <Content />
+ * </div>
+ * ```
+ */
+export function RightToLeftProgressiveBlur({
+  width,
+  className = "",
+  blurLevels = [1, 2, 4, 8, 16, 24, 32, 40],
+}: RightToLeftProgressiveBlurProps) {
+  const numLayers = blurLevels.length;
+
+  return (
+    <div
+      className={cn(
+        "absolute top-0 bottom-0 pointer-events-none",
+        className
+      )}
+      style={{ width }}
+    >
+      {blurLevels.map((blur, index) => {
+        // Each layer starts from the right and extends further left
+        // Layer 0 (lowest blur): covers 0% - 12.5%
+        // Layer N (highest blur): covers 0% - 100%
+        const endPercent = ((index + 1) / numLayers) * 100;
+
+        const maskGradient = `linear-gradient(to right,
+          rgba(0,0,0,1) 0%,
+          rgba(0,0,0,1) ${endPercent}%,
+          rgba(0,0,0,0) ${Math.min(100, endPercent + 5)}%,
+          rgba(0,0,0,0) 100%
+        )`;
+
+        return (
+          <div
+            key={`blur-layer-${index}`}
+            className="absolute inset-0"
+            style={{
+              zIndex: index + 1,
+              backdropFilter: `blur(${blur}px)`,
+              WebkitBackdropFilter: `blur(${blur}px)`,
+              maskImage: maskGradient,
+              WebkitMaskImage: maskGradient,
+            }}
+          />
+        );
+      })}
+    </div>
+  );
+}

package/src/primitives/ThemeToggle.tsx

@@ -0,0 +1,125 @@
+"use client";
+
+import React from "react";
+
+export interface ThemeToggleProps {
+  isDark?: boolean;
+  onToggle?: () => void;
+  className?: string;
+  position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+  disabled?: boolean;
+}
+
+/**
+ * ThemeToggle - A primitive floating button for toggling between light and dark themes
+ *
+ * A fixed-position button that displays a sun/moon icon based on the current theme.
+ * Commonly used for implementing dark mode toggles in applications.
+ *
+ * Features:
+ * - Fixed positioning with configurable corners
+ * - Animated icon transitions
+ * - Accessible with ARIA labels
+ * - Responsive hover and active states
+ * - Built-in disabled state
+ *
+ * @example
+ * ```tsx
+ * const [isDark, setIsDark] = useState(false);
+ *
+ * <ThemeToggle
+ *   isDark={isDark}
+ *   onToggle={() => setIsDark(!isDark)}
+ *   position="bottom-right"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With Next.js theme provider
+ * import { useTheme } from 'next-themes';
+ *
+ * function MyApp() {
+ *   const { theme, setTheme } = useTheme();
+ *   return (
+ *     <ThemeToggle
+ *       isDark={theme === 'dark'}
+ *       onToggle={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @param isDark - Whether dark mode is currently active (default: false)
+ * @param onToggle - Callback function when toggle is clicked
+ * @param className - Additional CSS classes for customization
+ * @param position - Corner position (default: "bottom-right")
+ * @param disabled - Disable the toggle button (default: false)
+ */
+export function ThemeToggle({
+  isDark = false,
+  onToggle,
+  className = "",
+  position = "bottom-right",
+  disabled = false,
+}: ThemeToggleProps) {
+  const positionClasses = {
+    "bottom-right": "bottom-6 right-6",
+    "bottom-left": "bottom-6 left-6",
+    "top-right": "top-6 right-6",
+    "top-left": "top-6 left-6",
+  }[position];
+
+  const handleClick = () => {
+    if (!disabled && onToggle) {
+      onToggle();
+    }
+  };
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      disabled={disabled}
+      className={`
+        fixed z-50 w-12 h-12 rounded-full shadow-lg transition-all duration-200
+        flex items-center justify-center
+        bg-background text-foreground border border-border hover:bg-muted
+        ${positionClasses}
+        ${disabled ? 'opacity-50 cursor-not-allowed' : 'hover:scale-105 active:scale-95 cursor-pointer'}
+        ${className}
+      `}
+      aria-label={`Switch to ${isDark ? 'light' : 'dark'} mode`}
+      title={`Switch to ${isDark ? 'light' : 'dark'} mode`}
+    >
+      {isDark ? (
+        // Sun icon for light mode
+        <svg
+          className="w-5 h-5"
+          fill="none"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth="2"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+        >
+          <circle cx="12" cy="12" r="5" />
+          <path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42" />
+        </svg>
+      ) : (
+        // Moon icon for dark mode
+        <svg
+          className="w-5 h-5"
+          fill="none"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth="2"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+        >
+          <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
+        </svg>
+      )}
+    </button>
+  );
+}

package/src/primitives/__tests__/story-coverage.test.ts

@@ -0,0 +1,98 @@
+/**
+ * ADR-0064 §3 Layer 3 — story-coverage gate.
+ *
+ * Every file in `src/primitives/*.tsx` must have a matching
+ * `src/primitives/stories/*.stories.tsx`. Fails CI on net-new
+ * primitives shipped without stories.
+ *
+ * Naming heuristic:
+ *   - `Button.tsx`   →  `Button.stories.tsx`           (PascalCase)
+ *   - `accordion.tsx` → `Accordion.stories.tsx`        (lowercase → PascalCase)
+ *   - `dropdown-menu.tsx` → `DropdownMenu.stories.tsx` (kebab → PascalCase)
+ *
+ * Allowlist (`PRIMITIVES_WITHOUT_STORIES`) is for files that are NOT
+ * actual primitives (e.g., utility components, animation helpers,
+ * brand-name components). Each entry needs a one-line comment explaining
+ * why it doesn't need a story.
+ */
+
+import { describe, it, expect } from "vitest";
+import { promises as fs } from "fs";
+import { join } from "path";
+
+const PRIMITIVES_DIR = join(__dirname, "..");
+const STORIES_DIR = join(__dirname, "..", "stories");
+
+/**
+ * Files in primitives/ that don't need a story. Each entry MUST cite
+ * a reason; reviewers reject without one.
+ */
+const PRIMITIVES_WITHOUT_STORIES = new Map<string, string>([
+  ["index", "barrel export, not a primitive"],
+  ["BrandLogo", "wraps next/image with brand-config props; no behavior to story"],
+  ["BrandName", "thin <span> reading from brand-config; covered by AppShell story when one exists"],
+  ["DragHintAnimation", "decorative animation; no a11y-relevant state surface"],
+  ["EdgeSwipeGuards", "iOS gesture-suppression overlay; no visible UI"],
+  ["FloatingActionGroup", "layout container; tested via composed-pattern stories when those land"],
+  ["ProductPrice", "formatter component; covered by formatter unit tests"],
+  ["ProgressiveBlur", "decorative blur overlay; no a11y-relevant state surface"],
+  ["scroll-fade", "decorative scroll mask; no a11y-relevant state surface"],
+  ["ColorSwatch", "TODO — story coverage gap; ADR-0064 §2 cleanup PR queues this"],
+  ["ThemeToggle", "TODO — story coverage gap; ADR-0064 §2 cleanup PR queues this"],
+]);
+
+function toPascal(slug: string): string {
+  return slug
+    .split(/[-_]/g)
+    .filter((s) => s.length > 0)
+    .map((s) => s[0].toUpperCase() + s.slice(1))
+    .join("");
+}
+
+describe("ADR-0064 §3 Layer 3 — primitive story coverage", () => {
+  it("every primitive has a matching .stories.tsx (or is allowlisted)", async () => {
+    const primitives = (await fs.readdir(PRIMITIVES_DIR))
+      .filter((f) => f.endsWith(".tsx"))
+      .map((f) => f.replace(/\.tsx$/, ""));
+
+    const stories = new Set(
+      (await fs.readdir(STORIES_DIR))
+        .filter((f) => f.endsWith(".stories.tsx"))
+        .map((f) => f.replace(/\.stories\.tsx$/, "")),
+    );
+
+    const violations: string[] = [];
+    for (const p of primitives) {
+      if (PRIMITIVES_WITHOUT_STORIES.has(p)) continue;
+      const expected = toPascal(p);
+      if (!stories.has(expected)) {
+        violations.push(`${p}.tsx → expected stories/${expected}.stories.tsx`);
+      }
+    }
+    if (violations.length > 0) {
+      throw new Error(
+        `Primitives without stories (ADR-0064 §3 Layer 3):\n  ${violations.join("\n  ")}\n` +
+          `Either add the story or allowlist with reason in PRIMITIVES_WITHOUT_STORIES.`,
+      );
+    }
+  });
+
+  it("every allowlist entry corresponds to a real primitive file", async () => {
+    const primitives = new Set(
+      (await fs.readdir(PRIMITIVES_DIR))
+        .filter((f) => f.endsWith(".tsx") || f === "index")
+        .map((f) => f.replace(/\.tsx$/, "")),
+    );
+    primitives.add("index");
+    const stale: string[] = [];
+    for (const allowed of PRIMITIVES_WITHOUT_STORIES.keys()) {
+      if (!primitives.has(allowed)) {
+        stale.push(allowed);
+      }
+    }
+    expect(
+      stale,
+      `Stale allowlist entries (primitive removed but exception remains): ${stale.join(", ")}`,
+    ).toEqual([]);
+  });
+});