handhold-sdk 1.0.0

package/src/ui/widget.css

@@ -0,0 +1,599 @@
+#handhold-container {
+  /* Light Theme Variables (Default) */
+  --hh-bg: #FFFFFF;
+  --hh-fg: #0F172A;
+  --hh-muted: #64748B;
+  --hh-muted-fg: #64748B;
+  --hh-border: #E2E8F0;
+  --hh-input: #F8FAFC;
+  /* --hh-primary and --hh-primary-dark are set via inline style */
+  --hh-primary-fg: #ffffff;
+  --hh-secondary: #F1F5F9;
+  --hh-secondary-fg: #0F172A;
+  --hh-accent: #E2E8F0;
+  --hh-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.10), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
+  --hh-card-bg: #FFFFFF;
+  --hh-card-active-bg: #F1F5F9;
+  --hh-radius: 6px;
+  --hh-backdrop: blur(8px);
+  --hh-skeleton: #E2E8F0;
+
+  font-family: 'Manrope', ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  z-index: var(--hh-z-index, 9999);
+  line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+#handhold-container.dark {
+  --hh-bg: #1e293b;
+  --hh-fg: #f8fafc;
+  --hh-muted: #94a3b8;
+  --hh-muted-fg: #cbd5e1;
+  --hh-border: #334155;
+  --hh-input: #0f172a;
+  --hh-secondary: #334155;
+  --hh-secondary-fg: #f8fafc;
+  --hh-accent: #475569;
+  --hh-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1);
+  --hh-card-bg: #1e293b;
+  --hh-card-active-bg: #334155;
+  --hh-skeleton: #334155;
+}
+
+#handhold-container * {
+  box-sizing: border-box;
+}
+
+/* Help Button (FAB) */
+.handhold-help-button {
+  position: fixed;
+  width: 56px;
+  height: 56px;
+  border-radius: 50%;
+  background: var(--hh-bg);
+  color: var(--hh-fg);
+  border: 2px solid var(--hh-border);
+  cursor: pointer;
+  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
+  z-index: var(--hh-z-index, 9999);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 24px;
+  font-weight: 500;
+  transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.handhold-help-button.position-bottom-right {
+  right: 32px;
+  bottom: 32px;
+}
+.handhold-help-button.position-bottom-left {
+  left: 32px;
+  bottom: 32px;
+}
+.handhold-help-button.position-top-right {
+  right: 32px;
+  top: 32px;
+}
+.handhold-help-button.position-top-left {
+  left: 32px;
+  top: 32px;
+}
+
+.handhold-help-button:hover {
+  transform: none;
+  box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1);
+  color: var(--hh-primary);
+  border-color: var(--hh-primary);
+}
+
+.handhold-help-button:active {
+  transform: none;
+}
+
+.handhold-help-button.hidden {
+  transform: scale(0) rotate(90deg);
+  opacity: 0;
+  pointer-events: none;
+}
+
+/* Widget Panel */
+.handhold-widget {
+  position: fixed;
+  width: 380px;
+  max-height: calc(100vh - 124px);
+  background: var(--hh-bg);
+  color: var(--hh-fg);
+  border-radius: var(--hh-radius);
+  border: 1px solid var(--hh-border);
+  box-shadow: var(--hh-shadow);
+  z-index: calc(var(--hh-z-index, 9999) + 1);
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  opacity: 0;
+  transform: translateY(10px) scale(0.98);
+  transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1);
+  pointer-events: none;
+}
+
+.handhold-widget.position-bottom-right {
+  right: 20px;
+  bottom: 24px;
+}
+.handhold-widget.position-bottom-left {
+  left: 20px;
+  bottom: 24px;
+}
+.handhold-widget.position-top-right {
+  right: 20px;
+  top: 24px;
+}
+.handhold-widget.position-top-left {
+  left: 20px;
+  top: 24px;
+}
+
+.handhold-widget.open {
+  opacity: 1;
+  transform: translateY(0) scale(1);
+  pointer-events: auto;
+}
+
+/* Widget Header */
+.handhold-widget-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 20px 24px 16px;
+  background: transparent;
+  border-bottom: 1px solid transparent;
+}
+
+.handhold-widget-title {
+  font-size: 18px;
+  font-weight: 700;
+  margin: 0;
+  color: var(--hh-fg);
+}
+
+.handhold-header-actions {
+   display: flex;
+   align-items: center;
+   gap: 8px;
+}
+
+.handhold-widget-close {
+  width: 56px;
+  height: 56px;
+  border-radius: 6px;
+  border: none;
+  background: transparent;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--hh-muted);
+  transition: all 0.2s;
+  padding: 0;
+}
+
+.handhold-widget-close:hover {
+  background: var(--hh-secondary);
+  color: var(--hh-fg);
+}
+
+/* Widget Body */
+.handhold-widget-body {
+  flex: 1;
+  overflow-y: auto;
+  padding: 0 24px 24px;
+  scrollbar-width: thin;
+  scrollbar-color: var(--hh-muted) transparent;
+}
+
+.handhold-widget-body::-webkit-scrollbar {
+  width: 4px;
+}
+.handhold-widget-body::-webkit-scrollbar-track {
+  background: transparent;
+}
+.handhold-widget-body::-webkit-scrollbar-thumb {
+  background: var(--hh-muted);
+  border-radius: 2px;
+}
+
+/* Search Input */
+.handhold-search-container {
+  margin-bottom: 24px;
+}
+
+.handhold-search-label {
+  display: block;
+  font-size: 14px;
+  font-weight: 600;
+  margin-bottom: 8px;
+  color: var(--hh-fg);
+}
+
+.handhold-input-wrapper {
+  position: relative;
+  display: flex;
+  align-items: center;
+}
+
+.handhold-search-input {
+  width: 100%;
+  padding: 12px 16px;
+  padding-right: 48px;
+  border: 2px solid var(--hh-border);
+  border-radius: 8px;
+  background: var(--hh-input);
+  color: var(--hh-fg);
+  font-size: 15px;
+  transition: all 0.2s;
+  outline: none;
+}
+
+.handhold-search-input:focus {
+  border-color: var(--hh-primary);
+  background: var(--hh-bg);
+  box-shadow: 0 0 0 3px rgba(var(--hh-primary), 0.1);
+}
+
+.handhold-send-btn {
+  position: absolute;
+  right: 6px;
+  top: 6px;
+  bottom: 6px;
+  width: 36px;
+  padding: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  background: transparent;
+  color: var(--hh-primary);
+  border-radius: 6px;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.handhold-send-btn:hover {
+  background: var(--hh-secondary);
+}
+
+/* Intent Menu */
+.handhold-section-title {
+  font-size: 13px;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  color: var(--hh-muted);
+  margin: 0 0 12px;
+  font-weight: 700;
+}
+
+.handhold-intent-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  padding: 12px 16px;
+  margin-bottom: 8px;
+  border: 1px solid var(--hh-border);
+  border-radius: 8px;
+  background: var(--hh-card-bg);
+  color: var(--hh-fg);
+  font-size: 15px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s;
+  text-align: left;
+}
+
+.handhold-btn-text {
+  flex-shrink: 0;
+  margin-left: 12px;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--hh-primary);
+  opacity: 0.7;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+.handhold-intent-item:hover {
+  background: var(--hh-card-active-bg);
+  border-color: var(--hh-primary);
+  transform: translateX(4px);
+}
+
+.handhold-divider {
+  height: 1px;
+  background: var(--hh-border);
+  margin: 24px 0;
+}
+
+.handhold-contact-support {
+  justify-content: center;
+  gap: 8px;
+  background: transparent;
+  border-style: dashed;
+}
+
+/* Loading State */
+.handhold-loading {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 40px 0;
+  color: var(--hh-muted);
+  text-align: center;
+}
+
+/* Skeleton Loading */
+.handhold-skeleton-container {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  padding: 8px 0;
+}
+
+.handhold-skeleton {
+  background-color: var(--hh-skeleton);
+  border-radius: 4px;
+  animation: handhold-pulse-bg 1.5s infinite ease-in-out;
+}
+
+@keyframes handhold-pulse-bg {
+  0% { opacity: 0.6; }
+  50% { opacity: 1; }
+  100% { opacity: 0.6; }
+}
+
+.handhold-skeleton.title {
+  height: 24px;
+  width: 60%;
+  margin-bottom: 8px;
+}
+
+.handhold-skeleton.text {
+  height: 16px;
+  width: 100%;
+}
+
+.handhold-skeleton.text.short {
+  width: 70%;
+}
+
+.handhold-skeleton.card {
+  height: 80px;
+  width: 100%;
+  border-radius: 8px;
+}
+
+/* Guidance View */
+.handhold-guidance {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.handhold-progress {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 8px;
+}
+
+.handhold-progress-bar {
+  flex: 1;
+  height: 6px;
+  background: var(--hh-secondary);
+  border-radius: 3px;
+  overflow: hidden;
+}
+
+.handhold-progress-fill {
+  height: 100%;
+  background: var(--hh-primary);
+  border-radius: 3px;
+  transition: width 0.3s ease;
+}
+
+.handhold-progress-text {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--hh-muted);
+}
+
+.handhold-guidance-summary {
+  font-size: 15px;
+  line-height: 1.5;
+  color: var(--hh-fg);
+  margin-bottom: 16px;
+}
+
+.handhold-step {
+  position: relative;
+  padding-left: 24px;
+  margin-bottom: 16px;
+}
+
+.handhold-step::before {
+  content: '';
+  position: absolute;
+  left: 7px;
+  top: 24px;
+  bottom: -24px;
+  width: 2px;
+  background: var(--hh-border);
+}
+
+.handhold-step:last-child::before {
+  display: none;
+}
+
+.handhold-step-card {
+  border: 1px solid var(--hh-border);
+  border-radius: 8px;
+  background: var(--hh-card-bg);
+  padding: 16px;
+  transition: all 0.2s;
+}
+
+.handhold-step.active .handhold-step-card {
+  border-color: var(--hh-primary);
+  box-shadow: 0 4px 12px -2px rgba(var(--hh-primary-rgb), 0.1);
+}
+
+.handhold-step.completed .handhold-step-card {
+  background: var(--hh-secondary);
+  opacity: 0.8;
+}
+
+.handhold-step-content {
+  display: flex;
+  gap: 12px;
+}
+
+.handhold-step-number {
+  width: 24px;
+  height: 24px;
+  border-radius: 50%;
+  background: var(--hh-secondary);
+  color: var(--hh-muted-fg);
+  font-size: 12px;
+  font-weight: 700;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.handhold-step.active .handhold-step-number {
+  background: var(--hh-primary);
+  color: var(--hh-primary-fg);
+}
+
+.handhold-step.completed .handhold-step-number {
+  background: var(--color-green-500); /* Need to ensure green is available or use var */
+  background: #10B981;
+  color: white;
+}
+
+.handhold-step-text {
+  font-size: 15px;
+  line-height: 1.5;
+  color: var(--hh-fg);
+}
+
+.handhold-step-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  margin-top: 12px;
+}
+
+/* Article View */
+.handhold-article {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.handhold-article-query {
+  font-size: 13px;
+  color: var(--hh-muted);
+  font-style: italic;
+  padding-bottom: 12px;
+  border-bottom: 1px solid var(--hh-border);
+}
+
+.handhold-article-title {
+  font-size: 20px;
+  font-weight: 700;
+  margin: 0;
+  color: var(--hh-fg);
+  line-height: 1.3;
+}
+
+.handhold-article-summary {
+  font-size: 16px;
+  line-height: 1.6;
+  color: var(--hh-fg);
+  padding: 16px;
+  background: var(--hh-secondary);
+  border-radius: 8px;
+  border-left: 4px solid var(--hh-primary);
+}
+
+.handhold-article-content {
+  font-size: 15px;
+  line-height: 1.6;
+  color: var(--hh-fg);
+}
+
+.handhold-article-content p {
+  margin-bottom: 16px;
+}
+
+.handhold-article-content ul {
+  padding-left: 20px;
+  margin-bottom: 16px;
+}
+
+.handhold-article-content li {
+  margin-bottom: 6px;
+}
+
+.handhold-article-actions {
+  margin-top: 24px;
+  padding-top: 16px;
+  border-top: 1px solid var(--hh-border);
+}
+
+/* Completion Screen */
+.handhold-completion {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  padding: 32px 24px;
+  gap: 16px;
+}
+
+.handhold-completion-icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 72px;
+  height: 72px;
+  border-radius: 50%;
+  background: #d1fae5;
+  color: #059669;
+  flex-shrink: 0;
+}
+
+.handhold-completion-title {
+  font-size: 20px;
+  font-weight: 700;
+  color: var(--hh-fg);
+  margin: 0;
+}
+
+.handhold-completion-message {
+  font-size: 14px;
+  color: var(--hh-muted);
+  line-height: 1.6;
+  margin: 0;
+}
+
+.handhold-completion-message strong {
+  color: var(--hh-fg);
+  font-weight: 600;
+}

package/src/utils/Logger.js

@@ -0,0 +1,132 @@
+/**
+ * Hand Hold SDK - Logger
+ * Configurable logging utility with log levels
+ */
+
+const LOG_LEVELS = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3,
+};
+
+class Logger {
+  constructor(config = {}) {
+    this.prefix = config.prefix || '[HandHold]';
+    this.level = LOG_LEVELS[config.logLevel] ?? LOG_LEVELS.warn;
+    this.enabled = config.debug !== false;
+  }
+
+  /**
+   * Set log level
+   * @param {string} level - 'error', 'warn', 'info', 'debug'
+   */
+  setLevel(level) {
+    if (LOG_LEVELS[level] !== undefined) {
+      this.level = LOG_LEVELS[level];
+    }
+  }
+
+  /**
+   * Enable/disable logging
+   * @param {boolean} enabled
+   */
+  setEnabled(enabled) {
+    this.enabled = enabled;
+  }
+
+  /**
+   * Format message with timestamp
+   */
+  _format(level, ...args) {
+    const timestamp = new Date().toISOString().split('T')[1].split('.')[0];
+    return [`${this.prefix} [${timestamp}] [${level.toUpperCase()}]`, ...args];
+  }
+
+  /**
+   * Log error message (always shown if enabled)
+   */
+  error(...args) {
+    if (!this.enabled) return;
+    if (this.level >= LOG_LEVELS.error) {
+      console.error(...this._format('error', ...args));
+    }
+  }
+
+  /**
+   * Log warning message
+   */
+  warn(...args) {
+    if (!this.enabled) return;
+    if (this.level >= LOG_LEVELS.warn) {
+      console.warn(...this._format('warn', ...args));
+    }
+  }
+
+  /**
+   * Log info message
+   */
+  info(...args) {
+    if (!this.enabled) return;
+    if (this.level >= LOG_LEVELS.info) {
+      console.info(...this._format('info', ...args));
+    }
+  }
+
+  /**
+   * Log debug message
+   */
+  debug(...args) {
+    if (!this.enabled) return;
+    if (this.level >= LOG_LEVELS.debug) {
+      console.log(...this._format('debug', ...args));
+    }
+  }
+
+  /**
+   * Log with custom level
+   */
+  log(level, ...args) {
+    const method = this[level];
+    if (typeof method === 'function') {
+      method.call(this, ...args);
+    }
+  }
+
+  /**
+   * Group logging
+   */
+  group(label) {
+    if (!this.enabled) return;
+    console.group(`${this.prefix} ${label}`);
+  }
+
+  /**
+   * End group
+   */
+  groupEnd() {
+    if (!this.enabled) return;
+    console.groupEnd();
+  }
+
+  /**
+   * Time measurement start
+   */
+  time(label) {
+    if (!this.enabled) return;
+    console.time(`${this.prefix} ${label}`);
+  }
+
+  /**
+   * Time measurement end
+   */
+  timeEnd(label) {
+    if (!this.enabled) return;
+    console.timeEnd(`${this.prefix} ${label}`);
+  }
+}
+
+// Export singleton with default config
+const logger = new Logger();
+export default logger;
+export { Logger, LOG_LEVELS };