@peerbots/core 0.2.6 → 1.0.0

package/src/ui/patterns/Stepper.stories.tsx

@@ -0,0 +1,129 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Stepper } from "./Stepper";
+import { Button } from "../forms/Button";
+import { Heading, Text } from "../foundations/Typography";
+import React, { useState } from "react";
+
+const meta: Meta<typeof Stepper> = {
+  title: "Patterns/Stepper",
+  component: Stepper,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  argTypes: {
+    orientation: {
+      control: "select",
+      options: ["horizontal", "vertical", "chips"],
+    },
+    color: {
+      control: "select",
+      options: ["teal", "pink", "primary", "neutral"],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Stepper>;
+
+const sampleSteps = [
+  { id: "account", title: "Account", description: "Enter profile & email" },
+  { id: "robot", title: "Select Bot", description: "Choose CAD model" },
+  { id: "config", title: "Configure", description: "Set face parameters" },
+  { id: "review", title: "Review", description: "Confirm and deploy" },
+];
+
+export const Default: Story = {
+  args: {
+    steps: sampleSteps,
+    activeStepId: "config",
+    orientation: "horizontal",
+    color: "teal",
+    className: "pb:w-[600px]",
+  },
+};
+
+export const InteractiveWizard: Story = {
+  render: () => {
+    const [currentStepId, setCurrentStepId] = useState("robot");
+    const stepIdx = sampleSteps.findIndex((s) => s.id === currentStepId);
+
+    return (
+      <div className="pb:flex pb:flex-col pb:gap-6 pb:p-6 pb:bg-white pb:rounded-2xl pb:border pb:border-gray-100 pb:shadow-md pb:w-[560px]">
+        <Stepper
+          steps={sampleSteps}
+          activeStepId={currentStepId}
+          onStepClick={setCurrentStepId}
+          color="teal"
+        />
+
+        <div className="pb:p-6 pb:bg-gray-50 pb:rounded-xl pb:text-center pb:space-y-2">
+          <Heading level={3} color="darkblue">
+            Step {stepIdx + 1}: {sampleSteps[stepIdx].title}
+          </Heading>
+          <Text size="sm" color="muted">
+            {sampleSteps[stepIdx].description}
+          </Text>
+        </div>
+
+        <div className="pb:flex pb:items-center pb:justify-between">
+          <Button
+            color="neutral"
+            disabled={stepIdx === 0}
+            onClick={() => setCurrentStepId(sampleSteps[stepIdx - 1].id)}
+          >
+            Previous
+          </Button>
+          <Button
+            color="teal"
+            disabled={stepIdx === sampleSteps.length - 1}
+            onClick={() => setCurrentStepId(sampleSteps[stepIdx + 1].id)}
+          >
+            Next Step
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const BuildChipsGuide: Story = {
+  render: () => {
+    const [focused, setFocused] = useState("face");
+    const buildSteps = [
+      { id: "base", title: "1. Neck Base" },
+      { id: "servos", title: "2. Pan/Tilt Servos" },
+      { id: "face", title: "3. Face Plate" },
+      { id: "eyes", title: "4. OLED Displays" },
+      { id: "cover", title: "5. Outer Shell" },
+    ];
+
+    return (
+      <div className="pb:p-6 pb:bg-gray-50 pb:rounded-2xl pb:max-w-xl pb:space-y-4">
+        <Text size="xs" weight="bold" color="muted" className="pb:uppercase">
+          Assembly Steps — Click to Jump
+        </Text>
+        <Stepper
+          orientation="chips"
+          steps={buildSteps}
+          activeStepId={focused}
+          onStepClick={setFocused}
+          color="teal"
+        />
+      </div>
+    );
+  },
+};
+
+export const VerticalOrientation: Story = {
+  render: () => (
+    <div className="pb:p-6 pb:bg-white pb:rounded-2xl pb:border pb:border-gray-100 pb:w-[380px]">
+      <Stepper
+        orientation="vertical"
+        steps={sampleSteps}
+        activeStepId="robot"
+        color="pink"
+      />
+    </div>
+  ),
+};

package/src/ui/patterns/Stepper.tsx

@@ -0,0 +1,295 @@
+import React from "react";
+import { cn } from "../utils";
+import { Icon } from "../foundations/Icon";
+import { ComponentColor, ComponentSize } from "../types";
+
+export type StepStatus = "complete" | "current" | "upcoming" | "disabled";
+
+export interface StepItem {
+  id: string;
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  status?: StepStatus;
+  icon?: React.ReactNode;
+}
+
+export interface StepperProps {
+  /** Array of sequential steps */
+  steps: StepItem[];
+  /** Controlled currently active step id */
+  activeStepId?: string;
+  /** Callback fired when a step is clicked */
+  onStepClick?: (stepId: string) => void;
+  /** Layout orientation */
+  orientation?: "horizontal" | "vertical" | "chips";
+  /** Brand color theme */
+  color?: ComponentColor;
+  /** Size scale */
+  size?: ComponentSize;
+  className?: string;
+}
+
+const colorBadgeStyles: Record<string, { current: string; complete: string; line: string }> = {
+  teal: {
+    current: "pb:bg-peerbots-teal pb:text-gray-900 pb:ring-4 pb:ring-peerbots-teal/30",
+    complete: "pb:bg-peerbots-darkteal pb:text-white",
+    line: "pb:bg-peerbots-darkteal",
+  },
+  pink: {
+    current: "pb:bg-rose-700 pb:text-white pb:ring-4 pb:ring-rose-200",
+    complete: "pb:bg-rose-800 pb:text-white",
+    line: "pb:bg-rose-700",
+  },
+  primary: {
+    current: "pb:bg-primary pb:text-gray-900 pb:ring-4 pb:ring-primary/30",
+    complete: "pb:bg-dark-primary pb:text-white",
+    line: "pb:bg-dark-primary",
+  },
+  darkblue: {
+    current: "pb:bg-peerbots-darkblue pb:text-white pb:ring-4 pb:ring-peerbots-darkblue/20",
+    complete: "pb:bg-peerbots-darkblue pb:text-white",
+    line: "pb:bg-peerbots-darkblue",
+  },
+  neutral: {
+    current: "pb:bg-gray-900 pb:text-white pb:ring-4 pb:ring-gray-300",
+    complete: "pb:bg-gray-800 pb:text-white",
+    line: "pb:bg-gray-600",
+  },
+};
+
+export function Stepper({
+  steps,
+  activeStepId,
+  onStepClick,
+  orientation = "horizontal",
+  color = "teal",
+  size = "md",
+  className,
+}: StepperProps) {
+  const activeIndex = steps.findIndex((s) => s.id === activeStepId);
+  const colorStyle = colorBadgeStyles[color] || colorBadgeStyles.teal;
+
+  const resolveStatus = (step: StepItem, index: number): StepStatus => {
+    if (step.status) return step.status;
+    if (activeIndex === -1) return index === 0 ? "current" : "upcoming";
+    if (index < activeIndex) return "complete";
+    if (index === activeIndex) return "current";
+    return "upcoming";
+  };
+
+  // 1. "chips" compact jump mode (as in Moddy build guide)
+  if (orientation === "chips") {
+    return (
+      <ol
+        className={cn(
+          "pb:flex pb:flex-row pb:flex-wrap pb:items-center pb:gap-2 pb:list-none pb:p-0 pb:m-0",
+          className,
+        )}
+      >
+        {steps.map((step, idx) => {
+          const status = resolveStatus(step, idx);
+          const isCurrent = status === "current";
+          const isComplete = status === "complete";
+          const isClickable = Boolean(onStepClick) && status !== "disabled";
+          const stepLabel = typeof step.title === "string" ? `Step ${idx + 1}: ${step.title}` : `Step ${idx + 1}`;
+
+          return (
+            <li key={step.id}>
+              <button
+                type="button"
+                aria-label={stepLabel}
+                disabled={!isClickable}
+                onClick={() => onStepClick?.(step.id)}
+                className={cn(
+                  "pb:inline-flex pb:items-center pb:gap-1.5 pb:pl-1.5 pb:pr-3 pb:py-1 pb:rounded-full pb:border pb:transition-all pb:duration-150 pb:text-xs pb:font-bold",
+                  isClickable ? "pb:cursor-pointer" : "pb:cursor-default",
+                  isCurrent
+                    ? cn(colorStyle.current, "pb:shadow-sm")
+                    : isComplete
+                      ? "pb:bg-gray-100 pb:text-gray-900 pb:border-gray-300 pb:hover:border-peerbots-darkteal"
+                      : "pb:bg-white pb:text-gray-600 pb:border-gray-300 pb:hover:text-gray-900",
+                )}
+              >
+                <span
+                  className={cn(
+                    "pb:flex pb:items-center pb:justify-center pb:w-4 pb:h-4 pb:rounded-full pb:text-[10px] pb:font-bold",
+                    isCurrent
+                      ? "pb:bg-black/15 pb:text-current"
+                      : isComplete
+                        ? "pb:bg-peerbots-darkteal pb:text-white"
+                        : "pb:bg-gray-200 pb:text-gray-700",
+                  )}
+                >
+                  {isComplete ? (
+                    <Icon name="check" className="pb:w-2.5 pb:pb:h-2.5" />
+                  ) : (
+                    idx + 1
+                  )}
+                </span>
+                <span className="pb:uppercase pb:tracking-tight pb:whitespace-nowrap">
+                  {step.title}
+                </span>
+              </button>
+            </li>
+          );
+        })}
+      </ol>
+    );
+  }
+
+  // 2. "vertical" layout mode
+  if (orientation === "vertical") {
+    return (
+      <ol
+        className={cn(
+          "pb:flex pb:flex-col pb:gap-0 pb:list-none pb:p-0 pb:m-0",
+          className,
+        )}
+      >
+        {steps.map((step, idx) => {
+          const status = resolveStatus(step, idx);
+          const isCurrent = status === "current";
+          const isComplete = status === "complete";
+          const isLast = idx === steps.length - 1;
+          const isClickable = Boolean(onStepClick) && status !== "disabled";
+          const stepLabel = typeof step.title === "string" ? `Step ${idx + 1}: ${step.title}` : `Step ${idx + 1}`;
+
+          return (
+            <li key={step.id} className="pb:relative pb:flex pb:items-start pb:gap-4 pb:pb-6">
+              {!isLast && (
+                <div
+                  className={cn(
+                    "pb:absolute pb:left-4 pb:top-8 pb:-bottom-0 pb:w-0.5 pb:bg-gray-200",
+                    isComplete && colorStyle.line,
+                  )}
+                />
+              )}
+
+              <button
+                type="button"
+                aria-label={stepLabel}
+                disabled={!isClickable}
+                onClick={() => onStepClick?.(step.id)}
+                className={cn(
+                  "pb:flex pb:items-center pb:justify-center pb:w-8 pb:h-8 pb:rounded-full pb:font-bold pb:text-xs pb:shrink-0 pb:transition-all pb:duration-200 pb:z-10",
+                  isClickable ? "pb:cursor-pointer" : "pb:cursor-default",
+                  isCurrent
+                    ? colorStyle.current
+                    : isComplete
+                      ? colorStyle.complete
+                      : "pb:bg-gray-100 pb:text-gray-700 pb:border pb:border-gray-300",
+                )}
+              >
+                {step.icon || (isComplete ? <Icon name="check" className="pb:w-4 pb:h-4" /> : idx + 1)}
+              </button>
+
+              <div
+                onClick={() => isClickable && onStepClick?.(step.id)}
+                className={cn(
+                  "pb:pt-0.5 pb:flex-1",
+                  isClickable && "pb:cursor-pointer",
+                )}
+              >
+                <div
+                  className={cn(
+                    "pb:text-sm pb:font-bold",
+                    isCurrent
+                      ? "pb:text-gray-950"
+                      : isComplete
+                        ? "pb:text-gray-900"
+                        : "pb:text-gray-600",
+                  )}
+                >
+                  {step.title}
+                </div>
+                {step.description && (
+                  <div className="pb:text-xs pb:text-gray-600 pb:mt-0.5 pb:leading-relaxed">
+                    {step.description}
+                  </div>
+                )}
+              </div>
+            </li>
+          );
+        })}
+      </ol>
+    );
+  }
+
+  // 3. "horizontal" rail mode (default)
+  return (
+    <ol
+      className={cn(
+        "pb:flex pb:w-full pb:items-center pb:justify-between pb:gap-0 pb:list-none pb:p-0 pb:m-0",
+        className,
+      )}
+    >
+      {steps.map((step, idx) => {
+        const status = resolveStatus(step, idx);
+        const isCurrent = status === "current";
+        const isComplete = status === "complete";
+        const isLast = idx === steps.length - 1;
+        const isClickable = Boolean(onStepClick) && status !== "disabled";
+        const stepLabel = typeof step.title === "string" ? `Step ${idx + 1}: ${step.title}` : `Step ${idx + 1}`;
+
+        return (
+          <li
+            key={step.id}
+            className={cn(
+              "pb:flex pb:items-center",
+              isLast ? "pb:flex-none" : "pb:flex-1",
+            )}
+          >
+            <div className="pb:flex pb:flex-col pb:items-center pb:text-center pb:relative">
+              <button
+                type="button"
+                aria-label={stepLabel}
+                disabled={!isClickable}
+                onClick={() => onStepClick?.(step.id)}
+                className={cn(
+                  "pb:flex pb:items-center pb:justify-center pb:w-9 pb:h-9 pb:rounded-full pb:font-bold pb:text-xs pb:transition-all pb:duration-200 pb:z-10",
+                  isClickable ? "pb:cursor-pointer" : "pb:cursor-default",
+                  isCurrent
+                    ? colorStyle.current
+                    : isComplete
+                      ? colorStyle.complete
+                      : "pb:bg-gray-100 pb:text-gray-700 pb:border pb:border-gray-300",
+                )}
+              >
+                {step.icon || (isComplete ? <Icon name="check" className="pb:w-4 pb:h-4" /> : idx + 1)}
+              </button>
+
+              <div className="pb:mt-2 pb:max-w-[120px]">
+                <div
+                  className={cn(
+                    "pb:text-xs pb:font-bold pb:leading-tight",
+                    isCurrent
+                      ? "pb:text-gray-950"
+                      : isComplete
+                        ? "pb:text-gray-900"
+                        : "pb:text-gray-600",
+                  )}
+                >
+                  {step.title}
+                </div>
+                {step.description && (
+                  <div className="pb:text-[10px] pb:text-gray-600 pb:mt-0.5 pb:hidden sm:pb:block truncate">
+                    {step.description}
+                  </div>
+                )}
+              </div>
+            </div>
+
+            {!isLast && (
+              <div
+                className={cn(
+                  "pb:flex-1 pb:h-0.5 pb:bg-gray-200 pb:mx-2 pb:transition-colors pb:duration-300 pb:-mt-6",
+                  isComplete && colorStyle.line,
+                )}
+              />
+            )}
+          </li>
+        );
+      })}
+    </ol>
+  );
+}

package/src/ui/{TabSelection.stories.tsx → patterns/TabSelection.stories.tsx}

@@ -3,7 +3,7 @@ import { TabSelection } from "./TabSelection";
 import React, { useState } from "react";
 
 const meta: Meta<typeof TabSelection> = {
-  title: "UI/TabSelection",
+  title: "Patterns/TabSelection",
   component: TabSelection,
   parameters: {
     layout: "centered",

package/src/ui/{TabSelection.tsx → patterns/TabSelection.tsx}

@@ -1,4 +1,4 @@
-import { Button, Icon } from ".";
+import { Button, Icon } from "..";
 import React from "react";
 
 export interface TabItem {
@@ -78,7 +78,7 @@ export function TabSelection({
       })}
       {onAddClick && (
         <Button
-          variant="primary"
+          color="primary"
           size="sm"
           aria-label="Create New Tab"
           onClick={onAddClick}

package/src/ui/patterns/index.ts

@@ -0,0 +1,6 @@
+export * from "./AuthFormUI";
+export * from "./TabSelection";
+export * from "./SearchInput";
+export * from "./CopyButton";
+export * from "./useClipboard";
+export * from "./Stepper";

package/src/ui/patterns/useClipboard.ts

@@ -0,0 +1,75 @@
+import { useState, useCallback, useRef, useEffect } from "react";
+
+export interface UseClipboardOptions {
+  /**
+   * Duration in milliseconds for the `copied` state to remain `true`.
+   * @default 2000
+   */
+  timeout?: number;
+  /** Callback fired after successfully copying to clipboard. */
+  onSuccess?: (text: string) => void;
+  /** Callback fired if copying fails. */
+  onError?: (error: Error) => void;
+}
+
+export function useClipboard(options: UseClipboardOptions = {}) {
+  const { timeout = 2000, onSuccess, onError } = options;
+  const [copied, setCopied] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const copy = useCallback(
+    async (text: string): Promise<boolean> => {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+      }
+
+      try {
+        if (navigator?.clipboard?.writeText) {
+          await navigator.clipboard.writeText(text);
+        } else {
+          // Fallback for non-secure / legacy contexts
+          const textarea = document.createElement("textarea");
+          textarea.value = text;
+          textarea.style.position = "fixed";
+          textarea.style.opacity = "0";
+          document.body.appendChild(textarea);
+          textarea.focus();
+          textarea.select();
+          const successful = document.execCommand("copy");
+          document.body.removeChild(textarea);
+          if (!successful) {
+            throw new Error("execCommand copy failed");
+          }
+        }
+
+        setCopied(true);
+        setError(null);
+        onSuccess?.(text);
+
+        timerRef.current = setTimeout(() => {
+          setCopied(false);
+        }, timeout);
+
+        return true;
+      } catch (err) {
+        const copyError = err instanceof Error ? err : new Error(String(err));
+        setError(copyError);
+        setCopied(false);
+        onError?.(copyError);
+        return false;
+      }
+    },
+    [timeout, onSuccess, onError],
+  );
+
+  useEffect(() => {
+    return () => {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+      }
+    };
+  }, []);
+
+  return { copy, copied, error };
+}

package/src/ui/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Canonical Peerbots Brand Palette
+ */
+export type BrandColor =
+  | "teal"       // Primary Brand Teal (#5fc7cc)
+  | "pink"       // Secondary Brand Pink (#e96c8a)
+  | "darkteal"   // High-Contrast Dark Teal (#3f8588)
+  | "darkblue"   // Deep Navy for Headings/Dark Surfaces (#2e3a59)
+  | "olive"      // Earthy Accent (#82871f)
+  | "dark"       // Dark Neutral / Near-Black (#1a1a1a)
+  | "light"      // Light Neutral / Off-White (#f8f9fa)
+  | "white";     // Pure White (#ffffff)
+
+/**
+ * Semantic Action & Status Intents
+ */
+export type IntentColor =
+  | "primary"    // High-emphasis main call-to-action (Electric Cyan #46d9d9)
+  | "neutral"    // Neutral, low-friction secondary action (Gray)
+  | "success"    // Positive confirmation (Green)
+  | "warning"    // Cautionary alert (Yellow/Amber)
+  | "danger"     // Destructive action / Error (Red)
+  | "info";      // Informational notice (Blue)
+
+/**
+ * Composite Color Token for UI Components
+ */
+export type ComponentColor = IntentColor | BrandColor;
+
+/**
+ * Visual Fill Style / Treatment
+ */
+export type FillVariant = "solid" | "soft" | "outline" | "ghost" | "link";
+
+/**
+ * Surface & Container Styles (Cards, Dialogs, Panels)
+ */
+export type SurfaceVariant = "surface" | "outline" | "glass" | "flat";
+
+/**
+ * Standard Sizing Scale
+ */
+export type ComponentSize = "xs" | "sm" | "md" | "lg" | "xl";
+
+/**
+ * Standard Geometric Border Radii
+ */
+export type ComponentRadius = "none" | "sm" | "md" | "lg" | "2xl" | "pill";

package/src/ui/Alert.stories.tsx

@@ -1,41 +0,0 @@
-import type { Meta, StoryObj } from "@storybook/react";
-import { Alert } from "./Alert";
-import React from "react";
-
-const meta: Meta<typeof Alert> = {
-  title: "UI/Alert",
-  component: Alert,
-  parameters: {
-    layout: "centered",
-  },
-};
-
-export default meta;
-
-type Story = StoryObj<typeof Alert>;
-
-export const Default: Story = {
-  args: {
-    level: "Info",
-    message: "This is a simple informational alert.",
-  },
-};
-
-export const Variations: Story = {
-  render: () => (
-    <div className="pb:flex pb:flex-col pb:gap-4 pb:w-[600px] pb:bg-gray-100 pb:p-8">
-      <Alert
-        level="Error"
-        message="Critical connection failure!"
-        action={{ name: "Retry", callback: () => alert("Retrying...") }}
-      />
-      <Alert level="Warning" message="Your session is about to expire." />
-      <Alert level="Success" message="Settings saved successfully." />
-      <Alert
-        level="Info"
-        message="New firmware update available."
-        action={{ name: "View", callback: () => alert("Viewing update...") }}
-      />
-    </div>
-  ),
-};

package/src/ui/Alert.tsx

@@ -1,72 +0,0 @@
-import { useState } from "react";
-import { Button, Icon } from ".";
-
-export type AlertLevel = "Error" | "Warning" | "Success" | "Info";
-
-export interface AlertAction {
-  name: string;
-  callback: () => void;
-}
-
-export interface AlertUIProps {
-  level: AlertLevel;
-  message: React.ReactNode;
-  action?: AlertAction;
-}
-
-export function Alert({ level, message, action }: AlertUIProps) {
-  const [showAlert, setShowAlert] = useState(true);
-
-  return (
-    <div
-      className={
-        "pb:flex pb:w-full pb:p-4 pb:m-1 pb:text-sm pb:rounded-lg pb:bg-white pb:border pb:border-solid pb:transition-opacity pb:ease-in-out pb:delay-150 pb:duration-300 " +
-        (showAlert ? " " : " pb:hidden")
-      }
-    >
-      <span>
-        {level === "Error" && (
-          <Icon
-            name="exclamationCircle"
-            size="lg"
-            className="pb:m-2"
-            stroke="red"
-          />
-        )}
-        {level === "Warning" && (
-          <Icon
-            name="exclamationTriangle"
-            size="lg"
-            className="pb:m-2"
-            stroke="yellow"
-          />
-        )}
-        {level === "Success" && (
-          <Icon name="checkCircle" size="lg" className="pb:m-2" stroke="green" />
-        )}
-        {level === "Info" && (
-          <Icon name="megaphone" size="lg" className="pb:m-2" />
-        )}
-      </span>
-      <span className="pb:flex pb:flex-1 pb:ml-2">{message}</span>
-      {action && (
-        <Button
-          onClick={() => {
-            action.callback();
-            setShowAlert(false);
-          }}
-        >
-          {action.name}
-        </Button>
-      )}
-      <span
-        className="pb:cursor-pointer"
-        onClick={() => {
-          setShowAlert(false);
-        }}
-      >
-        <Icon name="xCircle" size="lg" className="pb:m-1" />
-      </span>
-    </div>
-  );
-}