feat: TriggerButton component (attention/subtle/minimal), editor trigger config

Author: github4touchdouble

,

@@ -1,6 +1,6 @@
 {
   "name": "next-easytour",
-  "version": "0.3.0-alpha.19",
+  "version": "0.3.0-alpha.20",
   "description": "Generalizable interactive tutorial overlay library for React/Next.js. CSS-selector targeting, step actions, waitFor conditions, auto-scroll, highlight effects, animated transitions — all composable and declarative.",
   "keywords": [
     "tutorial",

package-lock.json

@@ -29,6 +29,7 @@ import type {
   SaveHandler,
   Step,
   TargetPoint,
+  TriggerConfig,
   ViewportAnchor,
 } from "../types";
 
@@ -53,6 +54,8 @@ interface Overrides {
   removedIds: string[];
   /** alpha.8: global card position for all steps without their own override. */
   defaultCardAnchor?: ViewportAnchor;
+  /** alpha.20: trigger button configuration. */
+  triggerConfig?: TriggerConfig;
 }
 
 const EMPTY_OVERRIDES: Overrides = {
@@ -64,6 +67,7 @@ const EMPTY_OVERRIDES: Overrides = {
   addedSteps: [],
   removedIds: [],
   defaultCardAnchor: undefined,
+  triggerConfig: undefined,
 };
 
 function unsavedCountOf(o: Overrides): number {
@@ -194,6 +198,9 @@ export interface EditorInternalApi {
   moveStep: (stepId: string, direction: "up" | "down") => void;
   /** alpha.8: set card position for ALL steps (global default). */
   setDefaultCardAnchor: (a: ViewportAnchor) => void;
+  /** alpha.20: trigger button config. */
+  triggerConfig?: TriggerConfig;
+  setTriggerConfig: (config: TriggerConfig) => void;
   save: () => Promise<void>;
   revert: () => void;
   saveStatus: EditorState["saveStatus"];
@@ -329,6 +336,10 @@ export function Editor<Meta = never>(props: EditorProps<Meta>) {
     setOverrides((p) => ({ ...p, defaultCardAnchor: a }));
   }, []);
 
+  const setTriggerConfig = useCallback((config: TriggerConfig) => {
+    setOverrides((p) => ({ ...p, triggerConfig: { ...(p.triggerConfig ?? {}), ...config } }));
+  }, []);
+
   const revert = useCallback(() => {
     setOverrides(EMPTY_OVERRIDES);
     setSaveStatus("idle");
@@ -375,11 +386,14 @@ export function Editor<Meta = never>(props: EditorProps<Meta>) {
       steps: mergedSteps as Step<unknown>[],
       setCardAnchor, clearCardAnchor, setArrowTip, setArrow, setCircles,
       updateStep, addStep, removeStep, moveStep,
-      setDefaultCardAnchor, save, revert, saveStatus,
+      setDefaultCardAnchor,
+      triggerConfig: overrides.triggerConfig,
+      setTriggerConfig,
+      save, revert, saveStatus,
     }),
     [active, overrides, mergedSteps, setCardAnchor, clearCardAnchor,
      setArrowTip, setArrow, setCircles, updateStep, addStep, removeStep,
-     moveStep, setDefaultCardAnchor, save, revert, saveStatus],
+     moveStep, setDefaultCardAnchor, setTriggerConfig, save, revert, saveStatus],
   );
 
   return (

package.json

@@ -12,7 +12,7 @@ import { useTutorial } from "../core/Tutorial";
 import { useEditor, type EditorInternalApi } from "./Editor";
 import { OverlayPortal } from "../core/OverlayPortal";
 import { targetPoint } from "../coords";
-import type { Step, TextLabel, TextLabelAnimation, TextLabelFrame } from "../types";
+import type { Step, TextLabel, TextLabelAnimation, TextLabelFrame, TriggerConfig } from "../types";
 
 // ── Icons ───────────────────────────────────────────────────────────────
 
@@ -124,6 +124,31 @@ export function EditorPanel(props: EditorPanelProps) {
 
       {!collapsed && (
         <>
+          {/* ── Trigger button config ── */}
+          <div className="eto-panel-trigger-section">
+            <div className="eto-panel-section-title">Trigger Button</div>
+            <div className="eto-panel-section-body">
+              <Field label="Text">
+                <input className="eto-panel-input"
+                  value={editor.triggerConfig?.text ?? "Start tutorial"}
+                  onChange={(e) => editor.setTriggerConfig({ text: e.target.value })}
+                  placeholder="Start tutorial" />
+              </Field>
+              <Field label="Mode">
+                <div className="eto-panel-toggles">
+                  {(["attention", "subtle", "minimal"] as const).map((m) => (
+                    <Pill key={m} label={m} active={(editor.triggerConfig?.mode ?? "subtle") === m}
+                      onChange={() => editor.setTriggerConfig({ mode: m })} />
+                  ))}
+                </div>
+              </Field>
+              <div className="eto-panel-toggles">
+                <Pill label="Show icon" active={editor.triggerConfig?.icon !== false}
+                  onChange={(on) => editor.setTriggerConfig({ icon: on })} />
+              </div>
+            </div>
+          </div>
+
           <div className="eto-panel-steps">
             {steps.map((s, i) => (
               <StepCard key={s.id} step={s} index={i} total={steps.length}

src/editor/Editor.tsx

@@ -20,6 +20,9 @@ export type { TooltipProps } from "./overlay/Tooltip";
 
 export { Labels } from "./overlay/Labels";
 
+export { TriggerButton } from "./overlay/TriggerButton";
+export type { TriggerButtonProps, TriggerMode } from "./overlay/TriggerButton";
+
 // Editor
 export { Editor, useEditorState } from "./editor/Editor";
 export type { EditorProps } from "./editor/Editor";
@@ -31,7 +34,7 @@ export type {
   TargetPoint, ViewportAnchor,
   Arrow as ArrowAnnotation, ArrowStyle, Circle, Annotations,
   Step, StepAction, WaitCondition, HighlightEffect, TransitionConfig,
-  TutorialStatus, TutorialApi, TutorialProps, TutorialTheme, TextLabel,
+  TutorialStatus, TutorialApi, TutorialProps, TutorialTheme, TriggerConfig, TextLabel,
   TextLabelAnimation, TextLabelFrame,
   CanEdit, EditorState, SaveHandler,
 } from "./types";

src/editor/EditorPanel.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+/**
+ * @module overlay/TriggerButton
+ *
+ * Alpha.20: configurable tutorial trigger button.
+ *
+ * Modes:
+ *   - "attention" — animated gradient pulse, impossible to miss
+ *   - "subtle"    — calm accent-tinted button
+ *   - "minimal"   — icon-only circle
+ *
+ * Hides automatically when the tutorial is active (stepId !== null).
+ * The host places it anywhere in their layout and provides `onClick`.
+ *
+ * ```tsx
+ * <TriggerButton
+ *   text="Take the tour"
+ *   mode="attention"
+ *   onClick={() => setStepId(steps[0].id)}
+ * />
+ * ```
+ */
+
+import * as React from "react";
+import { useTutorial } from "../core/Tutorial";
+
+// ── Types ───────────────────────────────────────────────────────────────
+
+export type TriggerMode = "attention" | "subtle" | "minimal";
+
+export interface TriggerButtonProps {
+  /** Click handler — typically calls setStepId(firstStep.id). */
+  onClick: () => void;
+  /** Button text. Default "Start tutorial". Ignored in "minimal" mode. */
+  text?: string;
+  /** Visual mode. Default "subtle". */
+  mode?: TriggerMode;
+  /** Show the help-circle icon. Default true. */
+  icon?: boolean;
+  /** Override the automatic hide-when-active behaviour. */
+  visible?: boolean;
+  /** Additional CSS class on the wrapper. */
+  className?: string;
+  /** Additional inline styles on the wrapper. */
+  style?: React.CSSProperties;
+}
+
+// ── Icon ────────────────────────────────────────────────────────────────
+
+function HelpIcon({ size = 14 }: { size?: number }) {
+  return (
+    <svg viewBox="0 0 24 24" width={size} height={size} fill="none"
+      stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <circle cx="12" cy="12" r="10" />
+      <path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3" />
+      <line x1="12" y1="17" x2="12.01" y2="17" />
+    </svg>
+  );
+}
+
+// ── Component ───────────────────────────────────────────────────────────
+
+export function TriggerButton(props: TriggerButtonProps) {
+  const {
+    onClick,
+    text = "Start tutorial",
+    mode = "subtle",
+    icon = true,
+    visible: visibleProp,
+    className,
+    style,
+  } = props;
+
+  const { step } = useTutorial();
+  const isActive = step !== null;
+
+  // Auto-hide when tutorial is running (unless overridden)
+  const visible = visibleProp ?? !isActive;
+  if (!visible) return null;
+
+  const cls = [
+    "eto-trigger",
+    `eto-trigger--${mode}`,
+    className,
+  ].filter(Boolean).join(" ");
+
+  return (
+    <button type="button" className={cls} style={style} onClick={onClick}>
+      {icon && <HelpIcon size={mode === "minimal" ? 16 : 14} />}
+      {mode !== "minimal" && <span className="eto-trigger-text">{text}</span>}
+    </button>
+  );
+}

src/index.ts

@@ -526,6 +526,13 @@
 /* Step list */
 .eto-panel-steps { flex: 1; overflow-y: auto; padding: 2px 0; }
 
+/* Trigger button config section */
+.eto-panel-trigger-section {
+  padding: 4px 8px 6px;
+  border-bottom: 1px solid var(--eto-border-soft);
+  flex-shrink: 0;
+}
+
 .eto-panel-step { border-bottom: 1px solid var(--eto-border-soft); }
 .eto-panel-step--active { background: color-mix(in srgb, var(--eto-accent) 5%, transparent); }
 
@@ -1053,4 +1060,105 @@
   align-items: center;
   justify-content: center;
   pointer-events: none;
+}
+
+/* ── TriggerButton (alpha.20) ────────────────────────────────────────
+   Tutorial start button with three visual modes. */
+
+.eto-trigger {
+  all: unset;
+  box-sizing: border-box;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  user-select: none;
+  -webkit-tap-highlight-color: transparent;
+}
+
+/* ── Subtle mode (default) ── */
+
+.eto-trigger--subtle {
+  padding: 5px 14px;
+  border-radius: 9999px;
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--eto-accent);
+  border: 1px solid color-mix(in srgb, var(--eto-accent) 30%, transparent);
+  background: color-mix(in srgb, var(--eto-accent) 6%, transparent);
+  box-shadow: 0 0 16px -4px color-mix(in srgb, var(--eto-accent) 20%, transparent);
+  transition: background 150ms, border-color 150ms, box-shadow 150ms;
+  animation: eto-trigger-enter 250ms ease-out;
+}
+.eto-trigger--subtle:hover {
+  background: color-mix(in srgb, var(--eto-accent) 12%, transparent);
+  border-color: color-mix(in srgb, var(--eto-accent) 50%, transparent);
+  box-shadow: 0 0 20px -2px color-mix(in srgb, var(--eto-accent) 30%, transparent);
+}
+.eto-trigger--subtle svg {
+  color: var(--eto-accent);
+}
+
+/* ── Attention mode (flashy) ── */
+
+.eto-trigger--attention {
+  padding: 6px 16px;
+  border-radius: 9999px;
+  font-size: 12px;
+  font-weight: 700;
+  color: #fff;
+  border: 1px solid rgba(255, 100, 100, 0.5);
+  background:
+    linear-gradient(90deg,
+      rgba(220,38,38,0.6) 0%,
+      rgba(255,100,100,0.85) 25%,
+      rgba(220,38,38,0.6) 50%,
+      rgba(180,20,20,0.7) 100%);
+  background-size: 200% 100%;
+  animation:
+    eto-trigger-sweep 1.2s linear infinite,
+    eto-trigger-glow 1.5s ease-in-out infinite,
+    eto-trigger-enter 250ms ease-out;
+}
+.eto-trigger--attention:hover {
+  filter: brightness(1.1);
+}
+.eto-trigger--attention svg {
+  color: rgba(255, 255, 255, 0.9);
+}
+
+/* ── Minimal mode (icon-only circle) ── */
+
+.eto-trigger--minimal {
+  padding: 6px;
+  border-radius: 9999px;
+  color: var(--eto-accent);
+  border: 1px solid color-mix(in srgb, var(--eto-accent) 25%, transparent);
+  background: color-mix(in srgb, var(--eto-accent) 5%, transparent);
+  transition: background 150ms, border-color 150ms;
+  animation: eto-trigger-enter 250ms ease-out;
+}
+.eto-trigger--minimal:hover {
+  background: color-mix(in srgb, var(--eto-accent) 12%, transparent);
+  border-color: color-mix(in srgb, var(--eto-accent) 40%, transparent);
+}
+
+.eto-trigger-text {
+  white-space: nowrap;
+}
+
+/* ── Trigger keyframes ── */
+
+@keyframes eto-trigger-enter {
+  from { opacity: 0; transform: scale(0.9); }
+  to   { opacity: 1; transform: scale(1); }
+}
+@keyframes eto-trigger-sweep {
+  from { background-position: 200% 0; }
+  to   { background-position: 0% 0; }
+}
+@keyframes eto-trigger-glow {
+  0%, 100% { box-shadow: 0 0 8px rgba(220, 38, 38, 0.3); }
+  50%      { box-shadow: 0 0 20px rgba(255, 100, 100, 0.6), 0 0 40px rgba(220, 38, 38, 0.2); }
 }

src/overlay/TriggerButton.tsx

@@ -318,4 +318,14 @@ export interface TutorialTheme {
   cardWidth?: string;
   /** Card border radius. Default "0.5rem". */
   cardRadius?: string;
+}
+
+/** Configuration for the tutorial trigger button. */
+export interface TriggerConfig {
+  /** Button text. Default "Start tutorial". */
+  text?: string;
+  /** Visual mode. Default "subtle". */
+  mode?: "attention" | "subtle" | "minimal";
+  /** Show help-circle icon. Default true. */
+  icon?: boolean;
 }