@snowcone-app/ui 0.1.43 → 0.2.0

package/src/primitives/DragHintAnimation.tsx

@@ -0,0 +1,190 @@
+import React from "react";
+
+export interface DragHintAnimationProps {
+  /** The position to center the animation */
+  position: { x: number; y: number };
+  /** Whether the drag direction is horizontal or vertical */
+  direction: "horizontal" | "vertical";
+}
+
+/**
+ * DragHintAnimation - Animated hand gesture hint for draggable elements
+ *
+ * Displays an animated hand icon that demonstrates drag interaction.
+ * Automatically fades in and out with a smooth animation cycle.
+ *
+ * @example
+ * ```tsx
+ * <DragHintAnimation
+ *   position={{ x: 0, y: 10 }}
+ *   direction="horizontal"
+ * />
+ * ```
+ */
+export function DragHintAnimation({ position, direction }: DragHintAnimationProps) {
+  return (
+    <div
+      className="drag-hint-container"
+      style={{
+        position: "absolute",
+        top: "50%",
+        left: "50%",
+        transform:
+          direction === "horizontal"
+            ? `translate(calc(-50% + ${position.x}px), -50%)`
+            : `translate(-50%, calc(-50% + ${position.y}px))`,
+        pointerEvents: "none",
+        zIndex: 3,
+        animation: "fadeInOut 2.2s ease-in-out forwards",
+      }}
+    >
+      <style>{`
+        @keyframes fadeInOut {
+          0% {
+            opacity: 0;
+          }
+          15% {
+            opacity: 1;
+          }
+          65% {
+            opacity: 1;
+          }
+          100% {
+            opacity: 0;
+          }
+        }
+
+        @keyframes handAnim {
+          0% {
+            left: 0;
+            opacity: 0;
+          }
+          10% {
+            left: 0;
+            opacity: 1;
+          }
+          35% {
+            left: 20px;
+            opacity: 1;
+          }
+          60% {
+            left: -20px;
+            opacity: 1;
+          }
+          80% {
+            left: 0;
+            opacity: 1;
+          }
+          100% {
+            left: 0;
+            opacity: 0;
+          }
+        }
+
+        @keyframes handAnimVertical {
+          0% {
+            top: 0;
+            opacity: 0;
+          }
+          10% {
+            top: 0;
+            opacity: 1;
+          }
+          35% {
+            top: 20px;
+            opacity: 1;
+          }
+          60% {
+            top: -20px;
+            opacity: 1;
+          }
+          80% {
+            top: 0;
+            opacity: 1;
+          }
+          100% {
+            top: 0;
+            opacity: 0;
+          }
+        }
+
+        @keyframes circleAnim {
+          0% {
+            transform: scale(0);
+            opacity: 0;
+          }
+          15% {
+            transform: scale(1);
+            opacity: 0.5;
+          }
+          30% {
+            transform: scale(1.5);
+            opacity: 0;
+          }
+        }
+
+        .hand-icon {
+          position: relative;
+        }
+
+        .hand {
+          background: var(--color-background, #fff);
+          width: 5px;
+          height: 16px;
+          border-radius: 20px;
+          position: relative;
+          left: -5px;
+          margin-bottom: 17px;
+          transform: rotate(0deg);
+          animation: ${
+            direction === "horizontal" ? "handAnim" : "handAnimVertical"
+          } 2s ease-in-out infinite;
+        }
+
+        .hand.vertical {
+          transform: rotate(90deg);
+          animation: handAnimVertical 2s ease-in-out infinite;
+        }
+
+        .hand:after {
+          content: "";
+          background: var(--color-background, #fff);
+          width: 17px;
+          height: 18px;
+          border-radius: 4px 8px 38px 15px;
+          transform: rotate(6deg) skewY(10deg);
+          position: absolute;
+          top: 13px;
+          left: -1px;
+        }
+
+        .hand:before {
+          content: "";
+          background: var(--color-background, #fff);
+          width: 6px;
+          height: 17px;
+          border-radius: 2px 40px 20px 20px;
+          position: absolute;
+          top: 12px;
+          left: -6px;
+          transform: rotate(-38deg);
+        }
+
+        .hand .circle {
+          background-color: var(--color-background, #fff);
+          width: 20px;
+          height: 20px;
+          border-radius: 50%;
+          position: absolute;
+          top: -7px;
+          left: -7px;
+          opacity: 0;
+          animation: circleAnim 0.5s ease-out forwards;
+        }
+      `}</style>
+      <div className="hand-icon">
+        <div className={`hand ${direction === "vertical" ? "vertical" : ""}`} />
+      </div>
+    </div>
+  );
+}

package/src/primitives/EdgeSwipeGuards.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import React, { useEffect } from "react";
+
+export interface EdgeSwipeGuardsProps {
+  /** Width of the edge zones in pixels (default: 20) */
+  width?: number;
+  /** Custom className for the guards */
+  className?: string;
+}
+
+/**
+ * EdgeSwipeGuards - Prevents iOS Safari's back/forward navigation gestures
+ * by intercepting horizontal touch-moves that start near the screen edges.
+ *
+ * Uses document-level touch listeners that check the touch origin position
+ * instead of overlay divs. This avoids blocking taps on UI elements (buttons,
+ * links) that happen to sit near the edges.
+ *
+ * @example
+ * ```tsx
+ * <EdgeSwipeGuards />
+ * <EdgeSwipeGuards width={30} />
+ * ```
+ */
+export function EdgeSwipeGuards({
+  width = 20,
+}: EdgeSwipeGuardsProps) {
+  useEffect(() => {
+    let touchStartX = -1;
+    let isEdgeTouch = false;
+
+    const handleTouchStart = (e: TouchEvent) => {
+      const x = e.touches[0].clientX;
+      const screenWidth = window.innerWidth;
+      isEdgeTouch = x <= width || x >= screenWidth - width;
+      touchStartX = x;
+    };
+
+    const handleTouchMove = (e: TouchEvent) => {
+      if (!isEdgeTouch) return;
+      const deltaX = Math.abs(e.touches[0].clientX - touchStartX);
+      // Only block horizontal swipes, not vertical scrolling
+      if (deltaX > 5) {
+        e.preventDefault();
+      }
+    };
+
+    document.addEventListener("touchstart", handleTouchStart, { passive: true });
+    document.addEventListener("touchmove", handleTouchMove, { passive: false });
+
+    return () => {
+      document.removeEventListener("touchstart", handleTouchStart);
+      document.removeEventListener("touchmove", handleTouchMove);
+    };
+  }, [width]);
+
+  // No DOM elements needed — this is purely event-based
+  return null;
+}

package/src/primitives/FloatingActionGroup.tsx

@@ -0,0 +1,176 @@
+import React from "react";
+
+export interface FloatingActionItem {
+  id: string;
+  label: string;
+  children?: React.ReactNode;
+  onClick?: (e?: any) => void;
+  selected?: boolean;
+  disabled?: boolean;
+  variant?: "circular" | "pill";
+}
+
+export interface FloatingActionGroupProps {
+  items: FloatingActionItem[];
+  className?: string;
+  scrollable?: boolean;
+  leftAligned?: boolean;
+  justify?: "start" | "end" | "center";
+  ariaLabel?: string;
+}
+
+/**
+ * FloatingActionGroup - A primitive component for displaying a horizontal group of action buttons
+ *
+ * Creates a row of circular or pill-shaped buttons with selection states and disabled states.
+ * Commonly used for filters, tabs, or quick actions. Supports horizontal scrolling for
+ * overflow scenarios.
+ *
+ * Features:
+ * - Two button variants: circular (icon-only) or pill (text-based)
+ * - Visual selection states with background effects
+ * - Optional horizontal scrolling with hidden scrollbars
+ * - Smart alignment modes (left, center, right)
+ * - Accessible with ARIA roles and labels
+ * - Dark mode support
+ *
+ * @example
+ * ```tsx
+ * // Simple button group
+ * <FloatingActionGroup
+ *   items={[
+ *     { id: '1', label: 'All', selected: true, onClick: () => setFilter('all') },
+ *     { id: '2', label: 'Active', onClick: () => setFilter('active') },
+ *     { id: '3', label: 'Done', onClick: () => setFilter('done') }
+ *   ]}
+ *   ariaLabel="Filter tasks"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Scrollable with custom icons
+ * <FloatingActionGroup
+ *   scrollable={true}
+ *   leftAligned={true}
+ *   items={[
+ *     { id: 'edit', label: 'Edit', variant: 'circular', children: <PencilIcon /> },
+ *     { id: 'delete', label: 'Delete', variant: 'circular', children: <TrashIcon />, disabled: true }
+ *   ]}
+ * />
+ * ```
+ *
+ * @param items - Array of action items to display
+ * @param className - Additional CSS classes
+ * @param scrollable - Enable horizontal scrolling for overflow (default: false)
+ * @param leftAligned - Add left padding in scrollable mode (default: false)
+ * @param justify - Horizontal alignment ("start", "end", or "center", default: "start")
+ * @param ariaLabel - Accessible label for the button group
+ */
+export function FloatingActionGroup({
+  items,
+  className = "",
+  scrollable = false,
+  leftAligned = false,
+  justify = "start",
+  ariaLabel,
+}: FloatingActionGroupProps) {
+  const baseContainerClass = "flex gap-2";
+
+  const containerClass = scrollable
+    ? `${baseContainerClass} overflow-x-auto scrollbar-hide ${
+        leftAligned ? "pl-6" : ""
+      }`
+    : baseContainerClass;
+
+  const justifyClass = {
+    start: "justify-start",
+    end: "justify-end",
+    center: "justify-center",
+  }[justify];
+
+  return (
+    <div
+      className={`${containerClass} ${justifyClass} ${className}`}
+      role="group"
+      aria-label={ariaLabel}
+    >
+      {items.map((item, index) => (
+        <FloatingActionButton
+          key={item.id}
+          {...item}
+          isFirstButton={index === 0}
+          leftAligned={leftAligned}
+          scrollable={scrollable}
+        />
+      ))}
+    </div>
+  );
+}
+
+function FloatingActionButton({
+  label,
+  children,
+  onClick,
+  selected = false,
+  disabled = false,
+  variant = "circular",
+  isFirstButton = false,
+  leftAligned = false,
+  scrollable = false,
+}: FloatingActionItem & {
+  isFirstButton?: boolean;
+  leftAligned?: boolean;
+  scrollable?: boolean;
+}) {
+  const baseButtonClass =
+    "flex items-center justify-center transition-all text-sm font-medium";
+
+  // Use rounded-fixed-full for circular to ensure it stays circular regardless of theme
+  // (e.g., brutalist themes set rounded-full to 0)
+  const shapeClass = variant === "circular" ? "rounded-fixed-full" : "rounded-button";
+
+  // When children are provided, don't apply padding/border - let the children define the size
+  const variantClass = children
+    ? ""
+    : variant === "circular"
+      ? "w-10 h-10"
+      : "px-4 py-2 border-2";
+
+  // When children are provided, don't apply background/border/opacity styles - let children control appearance
+  const stateClass = children
+    ? ""
+    : selected
+      ? "bg-background text-foreground border-primary"
+      : "bg-background text-foreground border-border/30 hover:border-border/60 opacity-60 hover:opacity-75";
+
+  const disabledClass = disabled
+    ? "opacity-50 cursor-not-allowed"
+    : "cursor-pointer";
+
+  // Smart alignment: add margin when first button is selected in left-aligned scrollable mode
+  const marginClass =
+    leftAligned && scrollable && isFirstButton && selected ? "ml-4" : "";
+
+  return (
+    <button
+      type="button"
+      onClick={disabled ? undefined : (e) => onClick?.(e)}
+      className={`${baseButtonClass} ${shapeClass} ${variantClass} ${stateClass} ${disabledClass} ${marginClass}`}
+      aria-label={label}
+      aria-pressed={selected}
+      disabled={disabled}
+    >
+      {children ? (
+        children
+      ) : (
+        <span className="relative">
+          {label}
+          {disabled && (
+            <span className="absolute inset-0 top-1/2 -translate-y-1/2 h-px bg-border opacity-50 pointer-events-none" aria-hidden="true" />
+          )}
+        </span>
+      )}
+    </button>
+  );
+}

package/src/primitives/ProductPrice.tsx

@@ -0,0 +1,171 @@
+import React from "react";
+import {
+  describeProductPrice,
+  formatPrice,
+  type ProductPriceOptions,
+} from "@snowcone-app/sdk";
+import { useProduct } from "../patterns/Product";
+
+export interface ProductPriceProps extends ProductPriceOptions {
+  contextPrice?: number;
+  showCents?: boolean;
+}
+
+/**
+ * ProductPrice - Formatted price display with currency and locale support
+ *
+ * A primitive component for displaying product prices with automatic currency
+ * formatting, smart cents display, and seamless Product context integration.
+ * Uses semantic HTML for machine-readable price data.
+ *
+ * Features:
+ * - Automatic currency formatting based on locale
+ * - Smart cents display (hides .00, shows actual cents)
+ * - Semantic HTML using `<data>` element with value attribute
+ * - Accessible with ARIA labels for screen readers
+ * - Works standalone or within Product context
+ * - Automatically uses currentPrice from context (reflects variant selection)
+ * - Supports international currencies and locales
+ * - Machine-readable price in value attribute for SEO/scrapers
+ *
+ * **Price Format:**
+ * - Prices are stored in cents to avoid floating point issues
+ * - Example: 2999 cents = $29.99
+ * - Automatically converts to display format
+ *
+ * **Context Integration:**
+ * - When used in `Product` context, automatically shows current price
+ * - Updates when user selects different variants
+ * - Falls back to prop value when used standalone
+ *
+ * @example
+ * ```tsx
+ * // Standalone usage with explicit price
+ * <ProductPrice price={2999} showCents={true} />
+ * // Output: $29.99
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Within Product context (automatically uses current price)
+ * <Product productId="shirt-123">
+ *   <ProductOptions />
+ *   <ProductPrice showCents={false} />
+ * </Product>
+ * // Output: $29 (or $35 if user selects a pricier variant)
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // International currency and locale
+ * <ProductPrice
+ *   price={2999}
+ *   currency="EUR"
+ *   locale="de-DE"
+ *   showCurrency={true}
+ * />
+ * // Output: €29,99
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styling for sale prices
+ * <div className="flex items-center gap-2">
+ *   <ProductPrice
+ *     price={1999}
+ *     className="text-2xl font-bold text-green-600"
+ *   />
+ *   <ProductPrice
+ *     price={2999}
+ *     showCents={false}
+ *     className="text-sm line-through text-gray-400"
+ *   />
+ * </div>
+ * ```
+ *
+ * @param price - Price in cents (e.g., 2999 = $29.99). Optional if used within Product context
+ * @param currency - ISO 4217 currency code (default: "USD")
+ * @param locale - BCP 47 locale string for formatting (default: "en-US")
+ * @param showCurrency - Display full currency symbol (default: false, shows $ only)
+ * @param showCents - Display cents portion (default: true, hides if .00)
+ * @param className - Additional CSS classes for styling
+ * @param contextPrice - Internal: Override context price (used by Product component)
+ */
+export function ProductPrice({
+  price,
+  currency = "USD",
+  locale = "en-US",
+  showCurrency = false,
+  className,
+  contextPrice,
+  showCents = true,
+}: ProductPriceProps) {
+  // Try to get price from context
+  let priceValue = contextPrice || price;
+  if (!priceValue) {
+    try {
+      const context = useProduct();
+      // Use the currentPrice from context which is already calculated
+      priceValue = context.currentPrice || context.product?.price;
+    } catch {
+      // Not in a Product context, that's OK
+    }
+  }
+
+  const descriptor = describeProductPrice(
+    { price, currency, locale, showCurrency, className },
+    priceValue
+  );
+
+  if (!descriptor) {
+    return null;
+  }
+
+  // Convert cents to dollars for display
+  const dollars = Math.floor(descriptor.price / 100);
+  const cents = descriptor.price % 100;
+
+  // Format with currency symbol if needed
+  const currencySymbol = showCurrency
+    ? new Intl.NumberFormat(descriptor.locale, {
+        style: "currency",
+        currency: descriptor.currency,
+      })
+        .format(0)
+        .replace(/[\d.,\s]/g, "")
+    : "$";
+
+  // Apply font-display only when no custom className is provided.
+  // When consumers pass className, they own the typography.
+  const priceClassName = descriptor.className || "font-display";
+
+  // If showing cents and there are cents to show
+  if (showCents && cents > 0) {
+    return (
+      <data
+        value={descriptor.price / 100}
+        className={priceClassName}
+        aria-label={`Price: ${currencySymbol}${dollars}.${cents.toString().padStart(2, "0")}`}
+      >
+        <span aria-hidden="true">
+          {currencySymbol}
+          {dollars}.{cents.toString().padStart(2, "0")}
+        </span>
+      </data>
+    );
+  }
+
+  // Just show dollars
+  return (
+    <data
+      value={descriptor.price / 100}
+      className={priceClassName}
+      aria-label={`Price: ${currencySymbol}${dollars}`}
+    >
+      <span aria-hidden="true">
+        {currencySymbol}
+        {dollars}
+      </span>
+    </data>
+  );
+}