@aravindc26/velu 0.12.8 → 0.12.9

package/src/engine-core/components/page-feedback-api.test.ts

@@ -0,0 +1,83 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  buildPublicFeedbackPayload,
+  PUBLIC_API_BASE_URL,
+  PUBLIC_FEEDBACK_ENDPOINT_PATH,
+  resolvePublicFeedbackEndpoint,
+  submitPublicFeedback,
+} from './page-feedback-api';
+
+test('buildPublicFeedbackPayload returns contract body with optional fields', () => {
+  const payload = buildPublicFeedbackPayload({
+    pageUrl: 'https://docs.example.com/guide',
+    helpful: true,
+    reasonText: 'The guide worked as expected',
+    details: '  Extra details  ',
+    email: '  user@example.com  ',
+  });
+
+  assert.deepEqual(payload, {
+    page_url: 'https://docs.example.com/guide',
+    helpful: true,
+    reason_text: 'The guide worked as expected',
+    details: 'Extra details',
+    email: 'user@example.com',
+  });
+});
+
+test('resolvePublicFeedbackEndpoint appends the fixed endpoint path', () => {
+  assert.equal(
+    resolvePublicFeedbackEndpoint(),
+    `${PUBLIC_API_BASE_URL}${PUBLIC_FEEDBACK_ENDPOINT_PATH}`,
+  );
+});
+
+test('submitPublicFeedback posts the expected payload and headers', async () => {
+  let receivedUrl = '';
+  let receivedInit: RequestInit | undefined;
+
+  const fetchImpl: typeof fetch = async (input, init) => {
+    receivedUrl = String(input);
+    receivedInit = init;
+    return new Response(null, { status: 204 });
+  };
+
+  const result = await submitPublicFeedback({
+    pageUrl: 'https://docs.example.com/page',
+    helpful: false,
+    reasonText: 'Update this documentation',
+    details: '',
+    email: undefined,
+    siteHost: 'docs.example.com',
+    fetchImpl,
+  });
+
+  assert.deepEqual(result, { ok: true });
+  assert.equal(receivedUrl, `${PUBLIC_API_BASE_URL}${PUBLIC_FEEDBACK_ENDPOINT_PATH}`);
+  assert.equal(receivedInit?.method, 'POST');
+  assert.equal(receivedInit?.credentials, 'include');
+  assert.equal(receivedInit?.body, JSON.stringify({
+    page_url: 'https://docs.example.com/page',
+    helpful: false,
+    reason_text: 'Update this documentation',
+  }));
+
+  const headers = receivedInit?.headers as Record<string, string>;
+  assert.deepEqual(headers, {
+    'Content-Type': 'application/json',
+    'x-velu-site-host': 'docs.example.com',
+  });
+});
+
+test('submitPublicFeedback reports non-2xx responses as request_failed', async () => {
+  const result = await submitPublicFeedback({
+    pageUrl: 'https://docs.example.com/page',
+    helpful: true,
+    reasonText: 'Something else',
+    siteHost: 'docs.example.com',
+    fetchImpl: async () => new Response(null, { status: 500 }),
+  });
+
+  assert.deepEqual(result, { ok: false, reason: 'request_failed', status: 500 });
+});

package/src/engine-core/components/page-feedback-api.ts

@@ -0,0 +1,89 @@
+export const PUBLIC_FEEDBACK_ENDPOINT_PATH = '/api/v1/public/feedback';
+export const PUBLIC_API_BASE_URL = 'https://api.getvelu.com';
+
+export interface PublicFeedbackPayload {
+  page_url: string;
+  helpful: boolean;
+  reason_text: string;
+  details?: string;
+  email?: string;
+}
+
+interface BuildPayloadInput {
+  pageUrl: string;
+  helpful: boolean;
+  reasonText: string;
+  details?: string;
+  email?: string;
+}
+
+export interface SubmitPublicFeedbackInput extends BuildPayloadInput {
+  siteHost: string;
+  fetchImpl?: typeof fetch;
+}
+
+type SubmitErrorReason = 'invalid_payload' | 'request_failed' | 'network_error';
+
+export type SubmitPublicFeedbackResult =
+  | { ok: true }
+  | { ok: false; reason: SubmitErrorReason; status?: number };
+
+function trimOptional(value: string | undefined): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export function resolvePublicFeedbackEndpoint(): string {
+  return `${PUBLIC_API_BASE_URL}${PUBLIC_FEEDBACK_ENDPOINT_PATH}`;
+}
+
+export function buildPublicFeedbackPayload(input: BuildPayloadInput): PublicFeedbackPayload | null {
+  const pageUrl = trimOptional(input.pageUrl);
+  const reasonText = trimOptional(input.reasonText);
+  if (!pageUrl || !reasonText) return null;
+
+  const payload: PublicFeedbackPayload = {
+    page_url: pageUrl,
+    helpful: input.helpful,
+    reason_text: reasonText,
+  };
+
+  const details = trimOptional(input.details);
+  if (details) payload.details = details;
+
+  const email = trimOptional(input.email);
+  if (email) payload.email = email;
+
+  return payload;
+}
+
+export async function submitPublicFeedback(input: SubmitPublicFeedbackInput): Promise<SubmitPublicFeedbackResult> {
+  const payload = buildPublicFeedbackPayload(input);
+  if (!payload) return { ok: false, reason: 'invalid_payload' };
+
+  const fetchImpl = input.fetchImpl ?? fetch;
+  try {
+    const response = await fetchImpl(resolvePublicFeedbackEndpoint(), {
+      method: 'POST',
+      credentials: 'include',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-velu-site-host': input.siteHost,
+      },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      return {
+        ok: false,
+        reason: 'request_failed',
+        status: response.status,
+      };
+    }
+
+    return { ok: true };
+  } catch {
+    return { ok: false, reason: 'network_error' };
+  }
+}

package/src/engine-core/components/page-feedback.tsx

@@ -0,0 +1,200 @@
+'use client';
+
+import { useState, type MouseEvent as ReactMouseEvent } from 'react';
+import { ThumbsDown, ThumbsUp } from 'lucide-react';
+import { submitPublicFeedback } from './page-feedback-api';
+
+type Vote = 'yes' | 'no';
+
+const YES_OPTIONS = [
+  'The guide worked as expected',
+  'It was easy to find the information I needed',
+  'It was easy to understand the product and features',
+  'The documentation is up to date',
+  'Something else',
+];
+
+const NO_OPTIONS = [
+  'Help me get started faster',
+  'Make it easier to find what I\'m looking for',
+  'Make it easy to understand the product and features',
+  'Update this documentation',
+  'Something else',
+];
+
+export function PageFeedback() {
+  const [vote, setVote] = useState<Vote | null>(null);
+  const [selectedReason, setSelectedReason] = useState<string>('');
+  const [details, setDetails] = useState('');
+  const [email, setEmail] = useState('');
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [submitError, setSubmitError] = useState(false);
+
+  const showForm = vote !== null;
+  const options = vote === 'yes' ? YES_OPTIONS : NO_OPTIONS;
+  const showOptionalInputs = selectedReason === 'Something else';
+  const canSubmit = vote !== null && selectedReason.trim().length > 0 && !isSubmitting;
+
+  const onChooseVote = (value: Vote) => {
+    if (vote === value) return;
+    setVote(value);
+    setSelectedReason('');
+    setDetails('');
+    setEmail('');
+    setSubmitError(false);
+  };
+
+  const stopEvent = (event: ReactMouseEvent) => {
+    event.preventDefault();
+    event.stopPropagation();
+  };
+
+  const onCancel = () => {
+    setVote(null);
+    setSelectedReason('');
+    setDetails('');
+    setEmail('');
+    setIsSubmitting(false);
+    setSubmitError(false);
+  };
+
+  const onSubmit = async () => {
+    if (!vote || !selectedReason.trim() || isSubmitting) return;
+
+    setIsSubmitting(true);
+    setSubmitError(false);
+
+    const result = await submitPublicFeedback({
+      helpful: vote === 'yes',
+      reasonText: selectedReason,
+      details: showOptionalInputs ? details : undefined,
+      email: showOptionalInputs ? email : undefined,
+      pageUrl: window.location.href,
+      siteHost: window.location.host,
+    });
+
+    if (result.ok) {
+      onCancel();
+      return;
+    }
+
+    setSubmitError(true);
+    setIsSubmitting(false);
+  };
+
+  return (
+    <div className="velu-page-feedback-block">
+      <div className="velu-page-feedback-row">
+        <p className="velu-page-feedback-question">Was this page helpful?</p>
+        <div className="velu-page-feedback-actions" role="group" aria-label="Feedback options">
+          <button
+            type="button"
+            className={['velu-page-feedback-btn', vote === 'yes' ? 'is-active' : ''].filter(Boolean).join(' ')}
+            aria-label="Mark page as helpful"
+            disabled={isSubmitting}
+            onClick={(event) => {
+              stopEvent(event);
+              onChooseVote('yes');
+            }}
+          >
+            <ThumbsUp />
+            <span>Yes</span>
+          </button>
+          <button
+            type="button"
+            className={['velu-page-feedback-btn', vote === 'no' ? 'is-active' : ''].filter(Boolean).join(' ')}
+            aria-label="Mark page as not helpful"
+            disabled={isSubmitting}
+            onClick={(event) => {
+              stopEvent(event);
+              onChooseVote('no');
+            }}
+          >
+            <ThumbsDown />
+            <span>No</span>
+          </button>
+        </div>
+      </div>
+
+      {showForm ? (
+        <div className="velu-page-feedback-panel">
+          <h3 className="velu-page-feedback-panel-title">
+            {vote === 'yes' ? 'Great! What worked best for you?' : 'How can we improve our product?'}
+          </h3>
+
+          <div className="velu-page-feedback-options" role="radiogroup" aria-label="Feedback reasons">
+            {options.map((option) => {
+              const checked = selectedReason === option;
+              return (
+                <button
+                  key={option}
+                  type="button"
+                  role="radio"
+                  aria-checked={checked}
+                  disabled={isSubmitting}
+                  className={['velu-page-feedback-option', checked ? 'is-checked' : ''].filter(Boolean).join(' ')}
+                  onClick={(event) => {
+                    stopEvent(event);
+                    setSelectedReason(option);
+                    setSubmitError(false);
+                  }}
+                >
+                  <span className="velu-page-feedback-radio" aria-hidden="true" />
+                  <span>{option}</span>
+                </button>
+              );
+            })}
+          </div>
+
+          {showOptionalInputs ? (
+            <div className="velu-page-feedback-inputs">
+              <textarea
+                className="velu-page-feedback-input"
+                rows={3}
+                placeholder="(Optional) Could you share more about your experience?"
+                value={details}
+                disabled={isSubmitting}
+                onChange={(event) => setDetails(event.target.value)}
+              />
+              <input
+                className="velu-page-feedback-input"
+                type="email"
+                placeholder="(Optional) Email"
+                value={email}
+                disabled={isSubmitting}
+                onChange={(event) => setEmail(event.target.value)}
+              />
+            </div>
+          ) : null}
+
+          <div className="velu-page-feedback-cta">
+            <button
+              type="button"
+              className="velu-page-feedback-cancel"
+              disabled={isSubmitting}
+              onClick={(event) => {
+                stopEvent(event);
+                onCancel();
+              }}
+            >
+              Cancel
+            </button>
+            <button
+              type="button"
+              className="velu-page-feedback-submit"
+              disabled={!canSubmit}
+              aria-busy={isSubmitting}
+              title={submitError ? 'Unable to submit feedback right now. Please try again.' : undefined}
+              onClick={(event) => {
+                stopEvent(event);
+                void onSubmit();
+              }}
+            >
+              Submit feedback
+            </button>
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/engine-core/components/product-switcher.tsx

@@ -0,0 +1,107 @@
+'use client';
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { usePathname } from 'next/navigation';
+import type { VeluProductOption, VeluIconLibrary } from '@core/types';
+import { VeluIcon } from './icon';
+
+function ChevronDownIcon() {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round">
+      <path d="m6 9 6 6 6-6" />
+    </svg>
+  );
+}
+
+function withTrailingSlashPath(path: string): string {
+  if (!path.startsWith('/')) return path;
+  if (path === '/' || path.endsWith('/')) return path;
+  return `${path}/`;
+}
+
+export function ProductSwitcher({
+  products,
+  iconLibrary,
+}: {
+  products: VeluProductOption[];
+  iconLibrary: VeluIconLibrary;
+}) {
+  const pathname = usePathname();
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  const current = useMemo(() => {
+    const firstSeg = pathname.split('/').filter(Boolean)[0] ?? '';
+    return products.find((p) => p.slug === firstSeg) ?? products[0];
+  }, [pathname, products]);
+
+  useEffect(() => {
+    function handleClick(e: MouseEvent) {
+      if (ref.current && !ref.current.contains(e.target as Node)) setOpen(false);
+    }
+    document.addEventListener('mousedown', handleClick);
+    return () => document.removeEventListener('mousedown', handleClick);
+  }, []);
+
+  if (!current || products.length <= 1) return null;
+
+  function switchTo(target: VeluProductOption) {
+    setOpen(false);
+
+    const segments = pathname.split('/').filter(Boolean);
+    const firstSeg = segments[0] ?? '';
+
+    if (current && current.slug === firstSeg) {
+      // Replace the product segment, keep tab/group/page segments
+      const rest = segments.slice(1);
+      if (rest.length > 0) {
+        window.location.href = withTrailingSlashPath('/' + [target.slug, ...rest].join('/'));
+        return;
+      }
+    }
+
+    window.location.href = withTrailingSlashPath(target.defaultPath);
+  }
+
+  return (
+    <div className="velu-product-switcher-wrap" ref={ref}>
+      <button type="button" className="velu-product-switcher" onClick={() => setOpen((v) => !v)}>
+        <span className="velu-product-switcher-label-wrap">
+          <VeluIcon
+            name={current.icon}
+            iconType={current.iconType}
+            library={iconLibrary}
+            className="velu-product-icon"
+          />
+          <span className="velu-product-switcher-label">{current.product}</span>
+        </span>
+        <ChevronDownIcon />
+      </button>
+      {open && (
+        <div className="velu-product-menu">
+          {products.map((product) => (
+            <button
+              key={product.slug}
+              type="button"
+              className={`velu-product-option ${product.slug === current.slug ? 'active' : ''}`}
+              onClick={() => switchTo(product)}
+            >
+              <span className="velu-product-option-name-wrap">
+                <VeluIcon
+                  name={product.icon}
+                  iconType={product.iconType}
+                  library={iconLibrary}
+                  className="velu-product-option-icon"
+                />
+                <span className="velu-product-option-name">{product.product}</span>
+              </span>
+              {product.description && (
+                <span className="velu-product-option-desc">{product.description}</span>
+              )}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/engine-core/components/prompt.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+import { isValidElement, useMemo, useState, type ReactNode } from 'react';
+import { VeluIcon } from './icon';
+
+function flattenText(node: ReactNode): string {
+  if (node == null || typeof node === 'boolean') return '';
+  if (typeof node === 'string' || typeof node === 'number') return String(node);
+  if (Array.isArray(node)) return node.map((item) => flattenText(item)).join('');
+  if (isValidElement(node)) return flattenText((node.props as { children?: ReactNode })?.children);
+  return '';
+}
+
+function renderInlineMarkdown(text: string): ReactNode[] {
+  const tokens = text.split(/(\*\*[^*]+\*\*|\*[^*]+\*)/g).filter(Boolean);
+  return tokens.map((token, index) => {
+    if (token.startsWith('**') && token.endsWith('**')) {
+      return <strong key={`b-${index}`}>{token.slice(2, -2)}</strong>;
+    }
+    if (token.startsWith('*') && token.endsWith('*')) {
+      return <em key={`i-${index}`}>{token.slice(1, -1)}</em>;
+    }
+    return <span key={`t-${index}`}>{token}</span>;
+  });
+}
+
+export function VeluPrompt({
+  description,
+  children,
+  icon,
+  iconType,
+  actions,
+  className,
+}: {
+  description?: string;
+  children?: ReactNode;
+  icon?: string;
+  iconType?: string;
+  actions?: string[];
+  className?: string;
+}) {
+  const [copied, setCopied] = useState(false);
+  const promptText = useMemo(() => flattenText(children).trim(), [children]);
+  const label = (description && description.trim()) || 'Prompt';
+  const actionSet = new Set((Array.isArray(actions) && actions.length > 0 ? actions : ['copy']).map((item) => String(item).toLowerCase()));
+  const showCopy = actionSet.has('copy');
+  const showCursor = actionSet.has('cursor');
+
+  const onCopy = async () => {
+    if (!promptText) return;
+    try {
+      await navigator.clipboard.writeText(promptText);
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 1200);
+    } catch {
+      // no-op
+    }
+  };
+
+  const onCursor = () => {
+    if (!promptText) return;
+    const url = `https://cursor.com/link/prompt?text=${encodeURIComponent(promptText)}`;
+    window.open(url, '_blank', 'noopener,noreferrer');
+  };
+
+  return (
+    <div className={['velu-prompt', className].filter(Boolean).join(' ')}>
+      <div className="velu-prompt-row">
+        <div className="velu-prompt-left">
+          {icon ? <VeluIcon name={icon} iconType={iconType} className="velu-prompt-icon" /> : null}
+          <div className="velu-prompt-desc">{renderInlineMarkdown(label)}</div>
+        </div>
+        <div className="velu-prompt-actions">
+          {showCopy ? (
+            <button type="button" className="velu-prompt-copy" onClick={onCopy}>
+              {copied ? 'Copied' : 'Copy prompt'}
+            </button>
+          ) : null}
+          {showCursor ? (
+            <button type="button" className="velu-prompt-open" onClick={onCursor}>
+              <img src="/icons/cursor-dark.svg" alt="" aria-hidden="true" className="velu-prompt-open-icon velu-prompt-open-icon-on-light" />
+              <img src="/icons/cursor-light.svg" alt="" aria-hidden="true" className="velu-prompt-open-icon velu-prompt-open-icon-on-dark" />
+              Open in Cursor
+            </button>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/engine-core/components/providers.tsx

@@ -0,0 +1,21 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { RootProvider } from 'fumadocs-ui/provider/next';
+import { PagefindSearch } from './search';
+
+interface ProvidersProps {
+  children: ReactNode;
+  theme?: {
+    defaultTheme: string;
+    enableSystem: boolean;
+  };
+}
+
+export function Providers({ children, theme }: ProvidersProps) {
+  return (
+    <RootProvider theme={theme} search={{ SearchDialog: PagefindSearch }}>
+      {children}
+    </RootProvider>
+  );
+}