From 48a7c43e23b90e409d5aca7efe7ef6780e041061 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Tue, 28 Apr 2026 07:42:30 -0500
Subject: [PATCH] PAP-2605: unify routine variables container and add help
 modal

Wrap the variables editor in a single rounded container so the
"Variables" header and the per-variable cards share one border with
internal dividers, instead of stacking as two visually separate
containers when expanded.

Add a help button to the variable instructions hint that opens a modal
explaining custom {{variable_name}} placeholders and the built-in
{{date}} and {{timestamp}} variables.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 ui/src/components/RoutineVariablesEditor.tsx | 121 +++++++++++++++++--
 1 file changed, 113 insertions(+), 8 deletions(-)

diff --git a/ui/src/components/RoutineVariablesEditor.tsx b/ui/src/components/RoutineVariablesEditor.tsx
index f6ecd32259c..cae1b0bc75d 100644
--- a/ui/src/components/RoutineVariablesEditor.tsx
+++ b/ui/src/components/RoutineVariablesEditor.tsx
@@ -1,8 +1,15 @@
 import { useEffect, useMemo, useState } from "react";
-import { ChevronDown, ChevronRight } from "lucide-react";
+import { ChevronDown, ChevronRight, HelpCircle } from "lucide-react";
 import { syncRoutineVariablesWithTemplate, type RoutineVariable } from "@paperclipai/shared";
 import { Badge } from "@/components/ui/badge";
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 import {
@@ -65,8 +72,8 @@ export function RoutineVariablesEditor({
   }
 
   return (
-    <Collapsible open={open} onOpenChange={setOpen}>
-      <CollapsibleTrigger className="flex w-full items-center justify-between rounded-lg border border-border/70 px-3 py-2 text-left">
+    <Collapsible open={open} onOpenChange={setOpen} className="overflow-hidden rounded-lg border border-border/70">
+      <CollapsibleTrigger className="flex w-full items-center justify-between px-3 py-2 text-left">
         <div>
           <p className="text-sm font-medium">Variables</p>
           <p className="text-xs text-muted-foreground">
@@ -75,9 +82,9 @@ export function RoutineVariablesEditor({
         </div>
         {open ? <ChevronDown className="h-4 w-4 text-muted-foreground" /> : <ChevronRight className="h-4 w-4 text-muted-foreground" />}
       </CollapsibleTrigger>
-      <CollapsibleContent className="space-y-3 pt-3">
+      <CollapsibleContent className="divide-y divide-border/70 border-t border-border/70">
         {syncedVariables.map((variable) => (
-          <div key={variable.name} className="rounded-lg border border-border/70 p-4">
+          <div key={variable.name} className="p-4">
             <div className="mb-3 flex flex-wrap items-center gap-2">
               <Badge variant="outline" className="font-mono text-xs">
                 {`{{${variable.name}}}`}
@@ -225,10 +232,108 @@ export function RoutineVariablesEditor({
   );
 }
 
+type BuiltinVariableDoc = {
+  name: string;
+  example: string;
+  description: string;
+};
+
+const BUILTIN_VARIABLE_DOCS: BuiltinVariableDoc[] = [
+  {
+    name: "date",
+    example: "2026-04-28",
+    description: "Current date in YYYY-MM-DD format (UTC) at the time the routine runs.",
+  },
+  {
+    name: "timestamp",
+    example: "April 28, 2026 at 12:17 PM UTC",
+    description: "Human-readable date and time (UTC) at the time the routine runs.",
+  },
+];
+
 export function RoutineVariablesHint() {
+  const [helpOpen, setHelpOpen] = useState(false);
+
   return (
-    <div className="rounded-lg border border-dashed border-border/70 px-3 py-2 text-xs text-muted-foreground">
-      Use `{"{{variable_name}}"}` placeholders in the instructions to prompt for inputs when the routine runs.
-    </div>
+    <>
+      <div className="flex items-center justify-between gap-2 rounded-lg border border-dashed border-border/70 px-3 py-2 text-xs text-muted-foreground">
+        <span>
+          Use `{"{{variable_name}}"}` placeholders in the instructions to prompt for inputs when the routine runs.
+        </span>
+        <button
+          type="button"
+          onClick={() => setHelpOpen(true)}
+          className="shrink-0 rounded-full p-0.5 text-muted-foreground transition-colors hover:bg-accent/50 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          aria-label="Show variable help"
+        >
+          <HelpCircle className="h-3.5 w-3.5" />
+        </button>
+      </div>
+
+      <Dialog open={helpOpen} onOpenChange={setHelpOpen}>
+        <DialogContent className="sm:max-w-xl">
+          <DialogHeader>
+            <DialogTitle>Routine variables</DialogTitle>
+            <DialogDescription>
+              How to prompt for inputs and which variables Paperclip fills in automatically.
+            </DialogDescription>
+          </DialogHeader>
+
+          <div className="space-y-5 text-sm">
+            <section className="space-y-2">
+              <h3 className="text-xs font-semibold uppercase tracking-[0.18em] text-muted-foreground">
+                Custom variables
+              </h3>
+              <p className="text-muted-foreground">
+                Type{" "}
+                <code className="rounded bg-muted px-1 py-0.5 font-mono text-xs text-foreground">
+                  {"{{variable_name}}"}
+                </code>{" "}
+                anywhere in the title or instructions. Paperclip detects each placeholder, lists it
+                under <span className="font-medium text-foreground">Variables</span>, and prompts
+                for a value before each run.
+              </p>
+              <ul className="list-disc space-y-1 pl-5 text-muted-foreground">
+                <li>Names must start with a letter and may use letters, numbers, and underscores.</li>
+                <li>Pick a type (text, textarea, number, boolean, select), default value, and whether it is required.</li>
+                <li>The same name reused across the title and instructions is treated as one variable.</li>
+              </ul>
+            </section>
+
+            <section className="space-y-2">
+              <h3 className="text-xs font-semibold uppercase tracking-[0.18em] text-muted-foreground">
+                Built-in variables
+              </h3>
+              <p className="text-muted-foreground">
+                These are filled in automatically — no setup needed and they will not appear in the
+                Variables list.
+              </p>
+              <div className="overflow-hidden rounded-lg border border-border/70">
+                <table className="w-full text-left text-xs">
+                  <thead className="bg-muted/40 text-muted-foreground">
+                    <tr>
+                      <th className="px-3 py-2 font-medium">Placeholder</th>
+                      <th className="px-3 py-2 font-medium">Example</th>
+                      <th className="px-3 py-2 font-medium">Description</th>
+                    </tr>
+                  </thead>
+                  <tbody className="divide-y divide-border/70">
+                    {BUILTIN_VARIABLE_DOCS.map((entry) => (
+                      <tr key={entry.name} className="align-top">
+                        <td className="px-3 py-2">
+                          <Badge variant="outline" className="font-mono text-xs">{`{{${entry.name}}}`}</Badge>
+                        </td>
+                        <td className="px-3 py-2 font-mono text-muted-foreground">{entry.example}</td>
+                        <td className="px-3 py-2 text-muted-foreground">{entry.description}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            </section>
+          </div>
+        </DialogContent>
+      </Dialog>
+    </>
   );
 }