@veluai/velu 0.2.18 → 0.2.19

package/package.json

@@ -1,64 +1,64 @@
-{
-  "name": "@veluai/velu",
-  "version": "0.2.18",
-  "type": "module",
-  "bin": "./dist/cli.js",
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "dist/**",
-    "src/runtime/**",
-    "src/navigation.js",
-    "src/template.html",
-    "src/lib/issues.js",
-    "src/lib/extract-mdx-error.js",
-    "src/lib/known-components.js",
-    "runtime/velu-ui/**",
-    "schema/**",
-    "templates/**"
-  ],
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "prepack": "node scripts/build.mjs",
-    "build:preview-runtime": "vite build -c vite.preview.config.mjs",
-    "test:parity": "node scripts/parity-test.mjs"
-  },
-  "dependencies": {
-    "@apidevtools/swagger-parser": "^10.1.0",
-    "@icons-pack/react-simple-icons": ">=13.0.0 <13.13.0",
-    "@mdx-js/mdx": "^3.1.1",
-    "@mdx-js/react": "^3.1.1",
-    "@mdx-js/rollup": "^3.1.1",
-    "@tailwindcss/vite": "^4.1.0",
-    "@vitejs/plugin-react": "^4.3.4",
-    "chokidar": "^3.6.0",
-    "estree-util-value-to-estree": "^3.5.0",
-    "express": "^4.21.1",
-    "github-slugger": "^2.0.0",
-    "iso-639-1": "^3.1.5",
-    "js-yaml": "^4.1.0",
-    "lucide-react": "^0.460.0",
-    "mdast-util-to-string": "^4.0.0",
-    "prism-react-renderer": "^2.4.0",
-    "prismjs": "^1.29.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "react-router-dom": "^6.28.0",
-    "rehype-slug": "^6.0.0",
-    "remark-frontmatter": "^5.0.0",
-    "remark-gfm": "^4.0.1",
-    "remark-mdx-frontmatter": "^5.2.0",
-    "tailwindcss": "^4.1.0",
-    "unist-util-visit": "^5.1.0",
-    "vite": "^5.4.11"
-  },
-  "devDependencies": {
-    "@fontsource/outfit": "^5.0.0",
-    "@resvg/resvg-js": "^2.6.2",
-    "esbuild": "^0.28.0",
-    "pagefind": "^1.3.0",
-    "playwright": "^1.48.0",
-    "satori": "^0.12.0"
-  }
-}
+{
+  "name": "@veluai/velu",
+  "version": "0.2.19",
+  "type": "module",
+  "bin": "./dist/cli.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/**",
+    "src/runtime/**",
+    "src/navigation.js",
+    "src/template.html",
+    "src/lib/issues.js",
+    "src/lib/extract-mdx-error.js",
+    "src/lib/known-components.js",
+    "runtime/velu-ui/**",
+    "schema/**",
+    "templates/**"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs",
+    "build:preview-runtime": "vite build -c vite.preview.config.mjs",
+    "test:parity": "node scripts/parity-test.mjs"
+  },
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^10.1.0",
+    "@icons-pack/react-simple-icons": ">=13.0.0 <13.13.0",
+    "@mdx-js/mdx": "^3.1.1",
+    "@mdx-js/react": "^3.1.1",
+    "@mdx-js/rollup": "^3.1.1",
+    "@tailwindcss/vite": "^4.1.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "chokidar": "^3.6.0",
+    "estree-util-value-to-estree": "^3.5.0",
+    "express": "^4.21.1",
+    "github-slugger": "^2.0.0",
+    "iso-639-1": "^3.1.5",
+    "js-yaml": "^4.1.0",
+    "lucide-react": "^0.460.0",
+    "mdast-util-to-string": "^4.0.0",
+    "prism-react-renderer": "^2.4.0",
+    "prismjs": "^1.29.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.28.0",
+    "rehype-slug": "^6.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-mdx-frontmatter": "^5.2.0",
+    "tailwindcss": "^4.1.0",
+    "unist-util-visit": "^5.1.0",
+    "vite": "^5.4.11"
+  },
+  "devDependencies": {
+    "@fontsource/outfit": "^5.0.0",
+    "@resvg/resvg-js": "^2.6.2",
+    "esbuild": "^0.28.0",
+    "pagefind": "^1.3.0",
+    "playwright": "^1.48.0",
+    "satori": "^0.12.0"
+  }
+}

package/runtime/velu-ui/index.js

@@ -45,6 +45,7 @@ export {
 export { default as Search } from './components/Search.jsx';
 export { default as pagefindSearch } from './lib/pagefind.js';
 export { createDocsAssistant } from './lib/docs-assistant.js';
+export { createPageFeedback } from './lib/page-feedback.js';
 export { default as Image } from './components/Image.jsx';
 export {
   default as CodeBlock,

package/runtime/velu-ui/lib/page-feedback.js

@@ -0,0 +1,72 @@
+/**
+ * page-feedback — runtime client for the "Was this page helpful?" widget on a
+ * published docs site. POSTs to the backend's PUBLIC feedback API:
+ *
+ *   POST /api/v1/public/feedback  ({ page_url, helpful, reason_text, details })
+ *
+ * Same contract as docs-assistant: the tenant is resolved from the
+ * `X-Velu-Site-Host` header (falls back to Origin), and the httponly visitor
+ * cookie rides along via `credentials: 'include'` (so the API must be same-site
+ * with the docs — true for *.getvelu.com subdomains).
+ *
+ * `createPageFeedback({ apiBase, host })` returns `{ submit }`, shaped to wire
+ * straight into <PageFeedback onVote onSubmit>. Returns null without an apiBase
+ * (dev preview / unconfigured site) so the widget stays purely visual.
+ */
+
+const trimSlash = (s) => String(s || '').replace(/\/+$/, '');
+
+function siteHost(explicit) {
+  if (explicit) return explicit;
+  return typeof window !== 'undefined' ? window.location.host : '';
+}
+
+// The page the feedback is about. Drop hash + query here; the backend
+// normalizes again server-side so per-page aggregation stays clean.
+function currentPageUrl() {
+  if (typeof window === 'undefined') return '';
+  const { origin, pathname } = window.location;
+  return origin + pathname;
+}
+
+export function createPageFeedback({ apiBase, host } = {}) {
+  const base = trimSlash(apiBase);
+  if (!base) return null;
+  const url = `${base}/api/v1/public/feedback`;
+
+  /**
+   * Send one feedback submission.
+   *  - helpful: boolean (Yes / No)
+   *  - reason:  short label from the "No" form (optional)
+   *  - detail:  free-text elaboration (optional)
+   * Best-effort: a failed request never disrupts the reader.
+   */
+  async function submit({ helpful, reason, detail } = {}) {
+    const body = {
+      page_url: currentPageUrl(),
+      helpful: !!helpful,
+      // reason_text is required by the API (min length 1); fall back to a
+      // sensible default when the reader didn't pick a reason (e.g. on "Yes").
+      reason_text:
+        (reason && String(reason).trim()) || (helpful ? 'Helpful' : 'Not helpful'),
+      details: detail ? String(detail) : null,
+    };
+    try {
+      await fetch(url, {
+        method: 'POST',
+        credentials: 'include',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Velu-Site-Host': siteHost(host),
+        },
+        body: JSON.stringify(body),
+      });
+    } catch {
+      /* feedback is best-effort — swallow network errors */
+    }
+  }
+
+  return { submit };
+}
+
+export default createPageFeedback;

package/src/runtime/App.jsx

@@ -41,6 +41,7 @@ import {
   Search,
   pagefindSearch,
   createDocsAssistant,
+  createPageFeedback,
   Logo,
   SocialLinks,
   Tree,
@@ -779,6 +780,17 @@ function DocsPage() {
     return createDocsAssistant({ apiBase, host: site.assistant?.host });
   }, []);
 
+  // Page-feedback backend: reuses the same injected apiBase as the assistant
+  // (baked into every published velu.json), so the "Was this page helpful?"
+  // widget can POST to /api/v1/public/feedback. Null in the dev preview, where
+  // the widget stays purely visual.
+  const pageFeedback = React.useMemo(() => {
+    if (IS_DEV_PREVIEW) return null;
+    const apiBase = site.assistant?.apiBase;
+    if (!apiBase) return null;
+    return createPageFeedback({ apiBase, host: site.assistant?.host });
+  }, []);
+
   const frontmatter = entry?.frontmatter ?? {};
   const PageComponent = entry?.Component ?? null;
   const pageToc = entry?.toc ?? [];
@@ -1572,7 +1584,18 @@ function DocsPage() {
           {/* Page-foot feedback widget — ref'd so the sticky AskBar
               above can hide as the user scrolls near it. */}
           <div ref={feedbackRef} style={{ marginTop: 'var(--s3)' }}>
-            <PageFeedback />
+            {/* key resets the widget's vote state on page change. "Yes"
+                submits immediately; "No" submits once its form is sent.
+                Handlers are no-ops in the dev preview (pageFeedback null). */}
+            <PageFeedback
+              key={pathname}
+              onVote={(v) => {
+                if (v === 'yes') pageFeedback?.submit({ helpful: true });
+              }}
+              onSubmit={({ reason, detail }) =>
+                pageFeedback?.submit({ helpful: false, reason, detail })
+              }
+            />
           </div>
           {/* Previous / next page navigation — derived from the
               sidebar reading order of the active section. */}