chati-dev 4.3.1 → 4.4.0

package/framework/scaffold/saas-dashboard/components/feedback/EmptyState.tsx.template

@@ -0,0 +1,281 @@
+/**
+ * components/feedback/EmptyState.tsx
+ * SaaS Dashboard Preset -- D_interaction phase
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Empty states are the most overlooked component in dashboard UIs.
+ * When data is absent, the screen goes blank, users panic ("Is it broken?"),
+ * and conversion to the first meaningful action drops. A well-crafted empty
+ * state communicates:
+ *
+ *   1. Context: what this section normally shows
+ *   2. Cause: why it's empty (first visit vs. filtered vs. no data)
+ *   3. Path: exactly one clear next action
+ *
+ * DESIGN DECISIONS
+ * ----------------
+ * 1. Illustration area reserved at 128px height (--space-32) before any
+ *    content loads. This prevents layout shift when the illustration
+ *    (icon or custom slot) appears. The PERFORMANCE requirement in the
+ *    spec mandates reserving space before content arrives.
+ *
+ * 2. Icon vs. illustration slot: the `icon` prop renders a Lucide icon at
+ *    48px in a circle container. The `illustration` prop (ReactNode) overrides
+ *    `icon` for custom SVGs or images, using the same reserved space.
+ *
+ * 3. Description max-width: 40ch. Prose in an empty state should be short
+ *    and direct -- 40 characters keeps it scannable at a single glance.
+ *
+ * 4. Secondary action: rendered as a ghost button below the primary action.
+ *    Used for "Learn more" or "Import from CSV" type escape hatches.
+ *
+ * 5. Centered layout: always centered, regardless of container width.
+ *    Empty states are spatial declarations -- they own the viewport slice
+ *    they occupy. Off-center empty states feel like layout bugs.
+ *
+ * ANIMATION
+ * ---------
+ * A gentle entrance stagger: icon scales up from 0.8 to 1 with ease-spring
+ * (delightful overshoot), then title and description fade in sequentially.
+ * This is reduced to opacity-only fade when prefers-reduced-motion is active.
+ * All transitions use transform and opacity only, never layout properties.
+ *
+ * TOKEN USAGE
+ * -----------
+ * All colors: CSS custom properties from globals.css.
+ * All spacing: CSS custom properties.
+ * No raw values in component styles.
+ */
+
+'use client';
+
+import { type ReactNode } from 'react';
+import { motion, useReducedMotion } from 'framer-motion';
+import { DURATION, EASING } from '@/lib/brand';
+import { Button } from '@/components/primitives/Button';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface EmptyStateAction {
+  label: string;
+  onClick: () => void;
+  /** Href converts button to a link. */
+  href?: string;
+  /** Lucide icon node (16px) */
+  icon?: ReactNode;
+}
+
+export interface EmptyStateProps {
+  /** Lucide icon rendered at 48px inside a circle container. */
+  icon?: ReactNode;
+  /** Custom illustration. Overrides `icon` when provided. */
+  illustration?: ReactNode;
+  /** Required heading. Uses type-h3 scale. */
+  title: string;
+  /** Supporting description. Capped at 40ch per spec. */
+  description?: string;
+  /** Primary call-to-action. */
+  primaryAction?: EmptyStateAction;
+  /** Secondary action (ghost style). */
+  secondaryAction?: EmptyStateAction;
+  /** Additional class on the container. */
+  className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export function EmptyState({
+  icon,
+  illustration,
+  title,
+  description,
+  primaryAction,
+  secondaryAction,
+  className,
+}: EmptyStateProps) {
+  const shouldReduceMotion = useReducedMotion();
+
+  const iconVariants = {
+    hidden: { opacity: 0, scale: shouldReduceMotion ? 1 : 0.8 },
+    visible: {
+      opacity: 1,
+      scale: 1,
+      transition: {
+        duration: shouldReduceMotion ? 0.08 : DURATION.medium / 1000,
+        ease: shouldReduceMotion ? EASING.out : EASING.spring,
+      },
+    },
+  };
+
+  const textVariants = {
+    hidden: { opacity: 0, y: shouldReduceMotion ? 0 : 8 },
+    visible: {
+      opacity: 1,
+      y: 0,
+      transition: {
+        duration: shouldReduceMotion ? 0.08 : DURATION.normal / 1000,
+        ease: EASING.out,
+      },
+    },
+  };
+
+  const actionsVariants = {
+    hidden: { opacity: 0, y: shouldReduceMotion ? 0 : 8 },
+    visible: {
+      opacity: 1,
+      y: 0,
+      transition: {
+        duration: shouldReduceMotion ? 0.08 : DURATION.normal / 1000,
+        ease: EASING.out,
+        delay: shouldReduceMotion ? 0 : 0.08,
+      },
+    },
+  };
+
+  return (
+    <div
+      className={className}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        textAlign: 'center',
+        padding: 'var(--spacing-section) var(--spacing-card-pad)',
+        gap: 'var(--space-4)',
+      }}
+    >
+      {/* Illustration area: reserved height prevents layout shift */}
+      <motion.div
+        variants={iconVariants}
+        initial="hidden"
+        animate="visible"
+        style={{
+          height: 'var(--space-32)', // 128px reserved
+          width: '128px',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          flexShrink: 0,
+        }}
+      >
+        {illustration ? (
+          // Custom illustration slot: uses the full reserved area
+          <div
+            style={{
+              width: '100%',
+              height: '100%',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+            }}
+          >
+            {illustration}
+          </div>
+        ) : icon ? (
+          // Icon in circle container
+          <div
+            aria-hidden="true"
+            style={{
+              width: '72px',
+              height: '72px',
+              borderRadius: 'var(--radius-circle)',
+              backgroundColor: 'var(--color-bg-raised)',
+              border: '1px solid var(--color-border-default)',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              color: 'var(--color-text-muted)',
+            }}
+          >
+            {icon}
+          </div>
+        ) : null}
+      </motion.div>
+
+      {/* Text content */}
+      <motion.div
+        variants={textVariants}
+        initial="hidden"
+        animate="visible"
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          alignItems: 'center',
+          gap: 'var(--space-2)',
+        }}
+      >
+        <h3
+          style={{
+            fontSize: 'var(--type-h3)',
+            lineHeight: 'var(--type-h3-lh)',
+            letterSpacing: 'var(--type-h3-ls)',
+            fontWeight: 600,
+            color: 'var(--color-text-primary)',
+            margin: 0,
+          }}
+        >
+          {title}
+        </h3>
+        {description && (
+          <p
+            style={{
+              fontSize: 'var(--type-body)',
+              lineHeight: 'var(--type-body-lh)',
+              color: 'var(--color-text-secondary)',
+              maxWidth: '40ch',
+              margin: 0,
+            }}
+          >
+            {description}
+          </p>
+        )}
+      </motion.div>
+
+      {/* Actions */}
+      {(primaryAction || secondaryAction) && (
+        <motion.div
+          variants={actionsVariants}
+          initial="hidden"
+          animate="visible"
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            gap: 'var(--space-3)',
+          }}
+        >
+          {primaryAction && (
+            <Button
+              variant="primary"
+              size="md"
+              href={primaryAction.href}
+              onClick={primaryAction.onClick}
+              iconLeft={primaryAction.icon}
+            >
+              {primaryAction.label}
+            </Button>
+          )}
+          {secondaryAction && (
+            <Button
+              variant="ghost"
+              size="sm"
+              href={secondaryAction.href}
+              onClick={secondaryAction.onClick}
+              iconLeft={secondaryAction.icon}
+            >
+              {secondaryAction.label}
+            </Button>
+          )}
+        </motion.div>
+      )}
+    </div>
+  );
+}
+
+export default EmptyState;