@startsimpli/ui 0.4.19 → 0.4.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.19",
+  "version": "0.4.22",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -31,9 +31,13 @@
     "@tanstack/react-query": ">=5.0.0",
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@startsimpli/auth": "0.4.20"
   },
   "peerDependenciesMeta": {
+    "@startsimpli/auth": {
+      "optional": true
+    },
     "@tanstack/react-query": {
       "optional": true
     }

package/src/components/workflows/WorkflowEmptyState.tsx

@@ -0,0 +1,256 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+import { Button } from '../ui/button';
+import {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+} from '../ui/card';
+import { Checkbox } from '../ui/checkbox';
+import { Label } from '../ui/label';
+import { Sparkles, PlayCircle, HelpCircle, X } from 'lucide-react';
+
+const STORAGE_KEY = 'workflow_guidance_dismissed';
+
+export interface WorkflowEmptyStateProps {
+  onOpenTemplateGallery: () => void;
+  onStartFromScratch: () => void;
+  onOpenHelp?: () => void;
+}
+
+/**
+ * Empty State Component for Workflow Canvas
+ *
+ * Provides first-time user guidance with two paths:
+ * 1. Template Gallery - Pre-built workflows to learn from
+ * 2. Start From Scratch - Opens node palette with guidance
+ *
+ * Features:
+ * - localStorage-based dismissal (respects user preference)
+ * - Non-intrusive inline design (not a modal)
+ * - Action-oriented messaging (not "Welcome!")
+ * - Re-accessible via help button
+ */
+export function WorkflowEmptyState({
+  onOpenTemplateGallery,
+  onStartFromScratch,
+  onOpenHelp,
+}: WorkflowEmptyStateProps) {
+  const [isDismissed, setIsDismissed] = useState(true);
+  const [dontShowAgain, setDontShowAgain] = useState(false);
+
+  useEffect(() => {
+    // Check if user has dismissed guidance
+    const dismissed = localStorage.getItem(STORAGE_KEY) === 'true';
+    setIsDismissed(dismissed);
+  }, []);
+
+  const handleTemplateGalleryClick = () => {
+    if (dontShowAgain) {
+      localStorage.setItem(STORAGE_KEY, 'true');
+    }
+    setIsDismissed(true);
+    onOpenTemplateGallery();
+  };
+
+  const handleStartFromScratchClick = () => {
+    if (dontShowAgain) {
+      localStorage.setItem(STORAGE_KEY, 'true');
+    }
+    setIsDismissed(true);
+    onStartFromScratch();
+  };
+
+  const handleDismiss = () => {
+    if (dontShowAgain) {
+      localStorage.setItem(STORAGE_KEY, 'true');
+    }
+    setIsDismissed(true);
+  };
+
+  if (isDismissed) {
+    // Show persistent help button for returning users
+    return (
+      <div className="absolute bottom-6 right-6 z-10">
+        <Button
+          variant="outline"
+          size="icon"
+          onClick={onOpenHelp}
+          className="h-12 w-12 rounded-full shadow-lg hover:shadow-xl transition-all"
+          title="Need help? View templates and guidance"
+        >
+          <HelpCircle className="h-5 w-5" />
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="flex items-center justify-center z-10"
+      role="dialog"
+      aria-labelledby="welcome-title"
+      aria-describedby="welcome-description"
+      aria-modal="false"
+    >
+      <Card className="w-full max-w-[720px] pointer-events-auto animate-in fade-in-0 zoom-in-95 duration-300 relative">
+        {/* Close button */}
+        <button
+          onClick={handleDismiss}
+          aria-label="Close welcome panel"
+          aria-keyshortcuts="Escape"
+          className="absolute right-4 top-4 rounded-full p-2 text-muted-foreground hover:bg-muted hover:text-foreground transition-colors"
+        >
+          <X className="w-5 h-5" aria-hidden="true" />
+        </button>
+
+        <CardHeader className="text-center pb-4 pt-10 px-10">
+          <CardTitle id="welcome-title" className="text-2xl font-semibold">
+            Welcome to Workflow Builder
+          </CardTitle>
+          <CardDescription
+            id="welcome-description"
+            className="text-sm text-muted-foreground leading-relaxed mt-2"
+          >
+            Create automated workflows with browser actions, logic, and AI
+          </CardDescription>
+        </CardHeader>
+
+        <CardContent className="flex flex-col gap-6 px-10 pb-10">
+          {/* Option 1: Template Gallery */}
+          <button
+            onClick={handleTemplateGalleryClick}
+            className="block w-full group text-left"
+            aria-label="Browse template gallery"
+            aria-describedby="template-gallery-desc"
+          >
+            <Card className="cursor-pointer transition-all duration-150 hover:shadow-md hover:border-primary/50 hover:scale-[1.02]">
+              <CardContent className="pt-6 pb-6">
+                <div className="flex items-start gap-4">
+                  <div className="flex-shrink-0">
+                    <div className="h-12 w-12 rounded-lg bg-primary/5 flex items-center justify-center group-hover:bg-primary/10 transition-colors">
+                      <Sparkles className="h-6 w-6 text-primary/60" />
+                    </div>
+                  </div>
+                  <div className="flex-1 text-left">
+                    <h3 className="font-medium text-base mb-1">
+                      Browse Template Gallery
+                    </h3>
+                    <p className="text-xs text-muted-foreground leading-relaxed">
+                      Start with a pre-built workflow and customize it to your
+                      needs. Perfect for learning common patterns.
+                    </p>
+                    <div className="mt-2 flex items-center gap-2 text-xs text-muted-foreground">
+                      <span className="inline-flex items-center gap-1">
+                        ⭐⭐⭐⭐⭐ Popular choice
+                      </span>
+                      <span>•</span>
+                      <span>5 templates available</span>
+                    </div>
+                  </div>
+                </div>
+              </CardContent>
+            </Card>
+            <span id="template-gallery-desc" className="sr-only">
+              Choose from 5 pre-built workflow templates including login flows,
+              data extraction, API integration, multi-page navigation, and form
+              submission.
+            </span>
+          </button>
+
+          {/* Option 2: Start From Scratch */}
+          <button
+            onClick={handleStartFromScratchClick}
+            className="block w-full group text-left"
+            aria-label="Start from scratch"
+            aria-describedby="start-scratch-desc"
+          >
+            <Card className="cursor-pointer transition-all duration-150 hover:shadow-md hover:border-primary/50 hover:scale-[1.02]">
+              <CardContent className="pt-6 pb-6">
+                <div className="flex items-start gap-4">
+                  <div className="flex-shrink-0">
+                    <div className="h-12 w-12 rounded-lg bg-primary/5 flex items-center justify-center group-hover:bg-primary/10 transition-colors">
+                      <PlayCircle className="h-6 w-6 text-primary/60" />
+                    </div>
+                  </div>
+                  <div className="flex-1 text-left">
+                    <h3 className="font-medium text-base mb-1">
+                      Start From Scratch
+                    </h3>
+                    <p className="text-xs text-muted-foreground leading-relaxed">
+                      Build your workflow from the ground up. We&apos;ll
+                      highlight the node palette and show you how to get started.
+                    </p>
+                    <div className="mt-2 text-xs text-muted-foreground">
+                      For experienced users
+                    </div>
+                  </div>
+                </div>
+              </CardContent>
+            </Card>
+            <span id="start-scratch-desc" className="sr-only">
+              Create a custom workflow by adding nodes from the node palette.
+              Ideal for users familiar with workflow automation.
+            </span>
+          </button>
+
+          {/* Don't show again checkbox */}
+          <div className="flex items-center justify-between pt-4 border-t">
+            <div className="flex items-center space-x-2">
+              <Checkbox
+                id="dontShowAgain"
+                checked={dontShowAgain}
+                onCheckedChange={(checked) => setDontShowAgain(checked === true)}
+              />
+              <Label
+                htmlFor="dontShowAgain"
+                className="text-sm text-muted-foreground cursor-pointer"
+              >
+                Don&apos;t show this again
+              </Label>
+            </div>
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={handleDismiss}
+              className="text-muted-foreground hover:text-foreground"
+            >
+              Close
+            </Button>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
+/**
+ * Hook to manage empty state visibility and reset.
+ */
+export function useWorkflowEmptyState() {
+  const [isGuidanceDismissed, setIsGuidanceDismissed] = useState(true);
+
+  useEffect(() => {
+    const dismissed = localStorage.getItem(STORAGE_KEY) === 'true';
+    setIsGuidanceDismissed(dismissed);
+  }, []);
+
+  const resetGuidance = () => {
+    localStorage.removeItem(STORAGE_KEY);
+    setIsGuidanceDismissed(false);
+  };
+
+  const dismissGuidance = () => {
+    localStorage.setItem(STORAGE_KEY, 'true');
+    setIsGuidanceDismissed(true);
+  };
+
+  return {
+    isGuidanceDismissed,
+    resetGuidance,
+    dismissGuidance,
+  };
+}

package/src/components/workflows/WorkflowVersionHistory.tsx

@@ -0,0 +1,151 @@
+'use client';
+
+import { useMemo } from 'react';
+import { Hash, User, StickyNote, Boxes } from 'lucide-react';
+import { cn } from '../../lib/utils';
+import { Badge } from '../ui/badge';
+
+/**
+ * Minimal, in-package shape of a workflow version. Mirrors the subset of the
+ * backend version record the history view actually reads — kept local so the
+ * component carries no app type coupling.
+ */
+export interface WorkflowVersion {
+  uuid: string;
+  versionNumber: number;
+  timestamp: string;
+  isPublished?: boolean;
+  versionNote?: string | null;
+  createdBy?: {
+    firstName?: string | null;
+    lastName?: string | null;
+    email: string;
+  } | null;
+  /** Opaque workflow definition; only `nodes.length` is read for display. */
+  workflowData?: Record<string, unknown> | null;
+}
+
+export interface WorkflowVersionHistoryProps {
+  versions: WorkflowVersion[];
+  /**
+   * Formats a version's ISO timestamp for display. Supplied by the consumer
+   * so this component stays free of date/locale dependencies. Defaults to the
+   * raw timestamp string when omitted.
+   */
+  formatTimestamp?: (timestamp: string) => string;
+  className?: string;
+}
+
+export function WorkflowVersionHistory({
+  versions,
+  formatTimestamp,
+  className,
+}: WorkflowVersionHistoryProps) {
+  const sorted = useMemo(
+    () => [...versions].sort((a, b) => b.versionNumber - a.versionNumber),
+    [versions]
+  );
+
+  if (versions.length === 0) {
+    return (
+      <div className={cn('text-center py-12', className)}>
+        <Hash className="h-12 w-12 mx-auto mb-3 text-muted-foreground" />
+        <h3 className="text-lg font-semibold mb-2">No Versions Yet</h3>
+        <p className="text-muted-foreground max-w-sm mx-auto">
+          No versions published yet. Use the canvas toolbar to publish a
+          version.
+        </p>
+      </div>
+    );
+  }
+
+  const formatTime = formatTimestamp ?? ((t: string) => t);
+
+  return (
+    <ol className={cn('relative space-y-6', className)}>
+      {sorted.map((version, index) => {
+        const label = version.versionNote
+          ? `v${version.versionNumber} — ${version.versionNote}`
+          : `v${version.versionNumber}`;
+
+        const nodeCount =
+          version.workflowData &&
+          Array.isArray(
+            (version.workflowData as Record<string, unknown>).nodes
+          )
+            ? (
+                (version.workflowData as Record<string, unknown>)
+                  .nodes as unknown[]
+              ).length
+            : null;
+
+        const isLast = index === sorted.length - 1;
+
+        return (
+          <li key={version.uuid} className="relative pl-8">
+            {/* Timeline rail + dot */}
+            {!isLast && (
+              <span
+                className="absolute left-[7px] top-5 bottom-[-1.5rem] w-px bg-border"
+                aria-hidden="true"
+              />
+            )}
+            <span
+              className={cn(
+                'absolute left-0 top-1 h-3.5 w-3.5 rounded-full border-2',
+                version.isPublished
+                  ? 'border-green-500 bg-green-500'
+                  : 'border-muted-foreground bg-background'
+              )}
+              aria-hidden="true"
+            />
+
+            <div className="flex items-center justify-between gap-2">
+              <span className="font-medium text-sm">{label}</span>
+              <span className="text-xs text-muted-foreground">
+                {formatTime(version.timestamp)}
+              </span>
+            </div>
+
+            <div className="mt-2 space-y-2 text-sm">
+              {version.isPublished && (
+                <div>
+                  <Badge
+                    variant="outline"
+                    className="border-green-200 bg-green-50 text-green-700 dark:border-green-800 dark:bg-green-950/30 dark:text-green-400"
+                  >
+                    Published
+                  </Badge>
+                </div>
+              )}
+              {version.createdBy && (
+                <div className="flex items-center gap-2 text-muted-foreground">
+                  <User className="h-3.5 w-3.5 shrink-0" />
+                  <span>
+                    {version.createdBy.firstName
+                      ? `${version.createdBy.firstName} ${version.createdBy.lastName ?? ''}`.trim()
+                      : version.createdBy.email}
+                  </span>
+                </div>
+              )}
+              {version.versionNote && (
+                <div className="flex items-start gap-2 text-muted-foreground">
+                  <StickyNote className="h-3.5 w-3.5 shrink-0 mt-0.5" />
+                  <span>{version.versionNote}</span>
+                </div>
+              )}
+              {nodeCount !== null && (
+                <div className="flex items-center gap-2 text-muted-foreground">
+                  <Boxes className="h-3.5 w-3.5 shrink-0" />
+                  <span>
+                    {nodeCount} node{nodeCount !== 1 ? 's' : ''}
+                  </span>
+                </div>
+              )}
+            </div>
+          </li>
+        );
+      })}
+    </ol>
+  );
+}

package/src/components/workflows/index.ts

@@ -76,3 +76,12 @@ export { useNodeStatusOverlay } from './hooks/useNodeStatusOverlay';
 
 // Category icon resolver (lucide)
 export { getCategoryIcon } from './node-icons';
+
+// Page composers — zero-coupling workflow UI (empty-state guidance + version history)
+export { WorkflowEmptyState, useWorkflowEmptyState } from './WorkflowEmptyState';
+export type { WorkflowEmptyStateProps } from './WorkflowEmptyState';
+export { WorkflowVersionHistory } from './WorkflowVersionHistory';
+export type {
+  WorkflowVersion,
+  WorkflowVersionHistoryProps,
+} from './WorkflowVersionHistory';