nodebb-plugin-search-agent 0.0.1

package/public/lib/main.js

@@ -0,0 +1,281 @@
+'use strict';
+
+/**
+ * Search Agent – client-side entry point.
+ *
+ * Responsibilities:
+ *  1. Inject the floating action button (FAB) into the page.
+ *  2. Render the chat panel HTML.
+ *  3. Handle open / close toggle.
+ *  4. Send queries to the backend API.
+ *  5. Render results (or error / empty states).
+ *
+ * All DOM work is deferred until NodeBB reports it is ready so that the
+ * app's Bootstrap and icon libraries are guaranteed to be present.
+ */
+
+// Use AMD require so the callback runs synchronously after the modules are
+// resolved — this avoids the race condition where 'action:app.load' has
+// already fired before an async await chain completes.
+console.log('[search-agent] main.js: module loaded');
+
+require(['hooks', 'api', 'translator'], function (hooks, api, translator) {
+	console.log('[search-agent] main.js: modules resolved, registering hooks');
+
+	// 'action:app.load' fires once after NodeBB initialises.
+	hooks.on('action:app.load', () => {
+		console.log('[search-agent] action:app.load fired — checking config before mounting');
+		mountIfAllowed({ api, translator });
+	});
+
+	// 'action:ajaxify.end' fires on every client-side navigation.
+	hooks.on('action:ajaxify.end', () => {
+		if (!document.getElementById('search-agent-fab')) {
+			console.log('[search-agent] action:ajaxify.end — FAB missing, re-checking config');
+			mountIfAllowed({ api, translator });
+		}
+	});
+});
+
+// ─── Visibility gate ──────────────────────────────────────────────────────────
+
+/**
+ * Fetch the plugin's public config, check whether the current user is allowed
+ * to see the widget, then mount (or skip) accordingly.
+ */
+function mountIfAllowed({ api, translator }) {
+	api.get('/plugins/search-agent/config', {})
+		.then(function (config) {
+			const user = window.app && window.app.user;
+			const isAdmin = user && user.isAdmin;
+			const uid = (user && user.uid) || 0;
+
+			if (config.visibleTo === 'admins' && !isAdmin) {
+				console.log('[search-agent] mountIfAllowed: widget hidden (admins only, user is not admin)');
+				return;
+			}
+
+			if (!config.guestsAllowed && uid === 0) {
+				console.log('[search-agent] mountIfAllowed: widget hidden (guests not allowed)');
+				return;
+			}
+
+			mountSearchAgent({ api, translator });
+		})
+		.catch(function (err) {
+			// Config fetch failed — mount anyway as a safe fallback
+			console.warn('[search-agent] mountIfAllowed: config fetch failed, mounting anyway', err);
+			mountSearchAgent({ api, translator });
+		});
+}
+
+// ─── HTML templates ───────────────────────────────────────────────────────────
+
+function buildFabHtml() {
+	return `
+		<button
+			id="search-agent-fab"
+			class="search-agent-fab"
+			aria-label="[[search-agent:fab-label]]"
+			title="[[search-agent:fab-label]]"
+		>
+			<i class="fa fa-comments" aria-hidden="true"></i>
+		</button>`;
+}
+
+function buildPanelHtml() {
+	return `
+		<div id="search-agent-panel" class="search-agent-panel" role="dialog" aria-modal="true" aria-label="[[search-agent:title]]" hidden>
+			<div class="search-agent-panel__header">
+				<span class="search-agent-panel__title">
+					<i class="fa fa-search"></i> [[search-agent:title]]
+				</span>
+				<button class="search-agent-panel__close" aria-label="[[search-agent:close-label]]" id="search-agent-close">
+					<i class="fa fa-times"></i>
+				</button>
+			</div>
+
+			<div class="search-agent-panel__body" id="search-agent-messages" aria-live="polite">
+				<div class="search-agent-bubble search-agent-bubble--bot">
+					[[search-agent:panel-greeting]]
+				</div>
+			</div>
+
+			<div class="search-agent-panel__footer">
+				<input
+					id="search-agent-input"
+					class="search-agent-input"
+					type="text"
+					placeholder="[[search-agent:input-placeholder]]"
+					maxlength="500"
+					autocomplete="off"
+				/>
+				<button id="search-agent-send" class="search-agent-send" aria-label="[[search-agent:send-label]]">
+					<i class="fa fa-paper-plane"></i>
+				</button>
+			</div>
+		</div>`;
+}
+
+// ─── Mount ────────────────────────────────────────────────────────────────────
+
+function mountSearchAgent({ api, translator }) {
+	console.log('[search-agent] mountSearchAgent: injecting FAB and chat panel into DOM');
+	// Avoid double-mounting if somehow called twice
+	if (document.getElementById('search-agent-fab')) {
+		console.log('[search-agent] mountSearchAgent: widget already mounted, skipping');
+		return;
+	}
+
+	const wrapper = document.createElement('div');
+	wrapper.className = 'search-agent-wrapper';
+
+	// Translate [[search-agent:key]] markers before inserting into the DOM
+	translator.translate(buildFabHtml() + buildPanelHtml(), function (translatedHtml) {
+		wrapper.innerHTML = translatedHtml;
+		document.body.appendChild(wrapper);
+
+		const fab = document.getElementById('search-agent-fab');
+		const panel = document.getElementById('search-agent-panel');
+		const closeBtn = document.getElementById('search-agent-close');
+		const input = document.getElementById('search-agent-input');
+		const sendBtn = document.getElementById('search-agent-send');
+		const messages = document.getElementById('search-agent-messages');
+
+		// ── Toggle panel ──────────────────────────────────────────────────────────
+		fab.addEventListener('click', () => {
+			const isOpen = !panel.hidden;
+			panel.hidden = isOpen;
+			fab.classList.toggle('search-agent-fab--active', !isOpen);
+			console.log(`[search-agent] FAB clicked — panel is now ${isOpen ? 'closed' : 'open'}`);
+			if (!isOpen) {
+				input.focus();
+			}
+		});
+
+		closeBtn.addEventListener('click', () => {
+			panel.hidden = true;
+			fab.classList.remove('search-agent-fab--active');
+		});
+
+		// Close on Escape
+		document.addEventListener('keydown', (e) => {
+			if (e.key === 'Escape' && !panel.hidden) {
+				panel.hidden = true;
+				fab.classList.remove('search-agent-fab--active');
+			}
+		});
+
+		// ── Submit on Enter or button click ───────────────────────────────────────
+		sendBtn.addEventListener('click', () => submitQuery({ api, translator, input, messages, sendBtn }));
+
+		input.addEventListener('keydown', (e) => {
+			if (e.key === 'Enter' && !e.shiftKey) {
+				e.preventDefault();
+				submitQuery({ api, translator, input, messages, sendBtn });
+			}
+		});
+	});
+}
+
+// ─── Chat logic ───────────────────────────────────────────────────────────────
+
+async function submitQuery({ api, translator, input, messages, sendBtn }) {
+	const queryText = input.value.trim();
+	console.log(`[search-agent] submitQuery: user submitted query="${queryText}"`);
+	if (!queryText) {
+		console.log('[search-agent] submitQuery: empty input, ignoring');
+		return;
+	}
+
+	// Show user bubble
+	appendBubble(messages, 'user', escapeHtml(queryText));
+	input.value = '';
+	input.disabled = true;
+	sendBtn.disabled = true;
+
+	// Typing indicator
+	const thinkingId = 'sa-thinking-' + Date.now();
+	appendBubble(messages, 'bot', '<span class="search-agent-typing"><span></span><span></span><span></span></span>', thinkingId);
+	scrollToBottom(messages);
+
+	try {
+		console.log('[search-agent] submitQuery: sending request to /plugins/search-agent/query');
+		const response = await api.post('/plugins/search-agent/query', { query: queryText });
+		removeBubble(messages, thinkingId);
+
+		const results = response && response.results;
+		console.log(`[search-agent] submitQuery: received ${results ? results.length : 0} result(s)`);
+
+		if (!results || results.length === 0) {
+			translator.translate(`[[search-agent:no-results, ${escapeHtml(queryText)}]]`, function (msg) {
+				appendBubble(messages, 'bot', `<em>${msg}</em>`);
+			});
+		} else {
+			const listItems = results
+				.map(r => `<li><a href="${escapeHtml(r.url)}" target="_blank" rel="noopener noreferrer">${escapeHtml(r.title)}</a></li>`)
+				.join('');
+
+			translator.translate('[[search-agent:results-header]]', function (header) {
+				appendBubble(
+					messages,
+					'bot',
+					`<p>${header}</p><ol class="search-agent-results">${listItems}</ol>`
+				);
+			});
+		}
+	} catch (err) {
+		console.log('[search-agent] submitQuery: request failed —', err);
+		removeBubble(messages, thinkingId);
+
+		let msgKey = 'error.server';
+		if (err && err.status === 403) {
+			msgKey = 'error.not-logged-in';
+		} else if (err && err.status === 400) {
+			msgKey = 'error.invalid-query';
+		}
+
+		translator.translate(`[[search-agent:${msgKey}]]`, function (msg) {
+			appendBubble(messages, 'bot error', `<em>${msg}</em>`);
+		});
+	} finally {
+		input.disabled = false;
+		sendBtn.disabled = false;
+		scrollToBottom(messages);
+		input.focus();
+	}
+}
+
+// ─── DOM utilities ────────────────────────────────────────────────────────────
+
+function appendBubble(container, typeClass, html, id) {
+	const div = document.createElement('div');
+	div.className = `search-agent-bubble search-agent-bubble--${typeClass}`;
+	if (id) {
+		div.id = id;
+	}
+	div.innerHTML = html;
+	container.appendChild(div);
+	scrollToBottom(container);
+}
+
+function removeBubble(container, id) {
+	const el = document.getElementById(id);
+	if (el && container.contains(el)) {
+		container.removeChild(el);
+	}
+}
+
+function scrollToBottom(container) {
+	container.scrollTop = container.scrollHeight;
+}
+
+function escapeHtml(str) {
+	return String(str)
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#039;');
+}
+

package/renovate.json

@@ -0,0 +1,5 @@
+{
+  "extends": [
+    "config:recommended"
+  ]
+}

package/scss/search-agent.scss

@@ -0,0 +1,374 @@
+// =============================================================================
+// Search Agent Plugin – styles
+// =============================================================================
+//
+// Layout overview
+// ---------------
+//  .search-agent-wrapper          Fixed positioning host (bottom-left corner)
+//    .search-agent-fab            Circular floating action button
+//    .search-agent-panel          Chat panel (hidden by default)
+//      .search-agent-panel__header
+//      .search-agent-panel__body  Scrollable message list
+//      .search-agent-panel__footer  Input + send button row
+//
+
+// ── Variables ─────────────────────────────────────────────────────────────────
+
+$sa-primary:        #0f7ee8;
+$sa-primary-dark:   #0a5fad;
+$sa-bg:             #ffffff;
+$sa-bg-header:      $sa-primary;
+$sa-border:         #dde3ec;
+$sa-bubble-user-bg: $sa-primary;
+$sa-bubble-bot-bg:  #f0f4f9;
+$sa-text-light:     #ffffff;
+$sa-text-dark:      #1a1a2e;
+$sa-error-bg:       #fdecea;
+$sa-error-border:   #f5c6cb;
+
+$sa-panel-width:    360px;
+$sa-panel-height:   500px;
+$sa-fab-size:       56px;
+$sa-fab-offset-x:   24px;
+$sa-fab-offset-y:   24px;
+$sa-border-radius:  16px;
+$sa-z-index:        9000;
+
+$sa-transition:     0.25s ease;
+
+// ── Wrapper (positioning host) ────────────────────────────────────────────────
+
+.search-agent-wrapper {
+	position: fixed;
+	bottom: $sa-fab-offset-y;
+	left:   $sa-fab-offset-x;
+	z-index: $sa-z-index;
+	display: flex;
+	flex-direction: column-reverse;  // panel grows upward from FAB
+	align-items: flex-start;
+	gap: 12px;
+}
+
+// ── Floating Action Button ─────────────────────────────────────────────────────
+
+.search-agent-fab {
+	width:  $sa-fab-size;
+	height: $sa-fab-size;
+	border-radius: 50%;
+	border: none;
+	background-color: $sa-primary;
+	color: $sa-text-light;
+	font-size: 22px;
+	cursor: pointer;
+	box-shadow: 0 4px 16px rgba(0, 0, 0, 0.25);
+	transition: background-color $sa-transition, transform $sa-transition, box-shadow $sa-transition;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	flex-shrink: 0;
+
+	&:hover {
+		background-color: $sa-primary-dark;
+		box-shadow: 0 6px 20px rgba(0, 0, 0, 0.30);
+	}
+
+	&:focus-visible {
+		outline: 3px solid $sa-primary;
+		outline-offset: 3px;
+	}
+
+	&--active {
+		transform: rotate(15deg);
+		background-color: $sa-primary-dark;
+
+		.fa-comments::before {
+			content: "\f075";  // solid comment bubble when open
+		}
+	}
+}
+
+// ── Chat Panel ────────────────────────────────────────────────────────────────
+
+.search-agent-panel {
+	width: $sa-panel-width;
+	height: $sa-panel-height;
+	background-color: $sa-bg;
+	border-radius: $sa-border-radius;
+	box-shadow: 0 8px 32px rgba(0, 0, 0, 0.18);
+	border: 1px solid $sa-border;
+	display: flex;
+	flex-direction: column;
+	overflow: hidden;
+	transform-origin: bottom left;
+	animation: sa-panel-in $sa-transition both;
+
+	@keyframes sa-panel-in {
+		from { opacity: 0; transform: scale(0.92) translateY(8px); }
+		to   { opacity: 1; transform: scale(1)    translateY(0);   }
+	}
+
+	// Responsive: use most of the screen on small viewports
+	@media (max-width: 420px) {
+		width: calc(100vw - #{$sa-fab-offset-x * 2});
+		height: 75vh;
+	}
+
+	&[hidden] {
+		display: none;
+	}
+
+	// ── Header ───────────────────────────────────────────────────────────────
+
+	&__header {
+		background-color: $sa-bg-header;
+		color: $sa-text-light;
+		padding: 12px 16px;
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		flex-shrink: 0;
+	}
+
+	&__title {
+		font-size: 15px;
+		font-weight: 600;
+		letter-spacing: 0.3px;
+
+		.fa {
+			margin-right: 6px;
+		}
+	}
+
+	&__close {
+		background: none;
+		border: none;
+		color: $sa-text-light;
+		font-size: 16px;
+		cursor: pointer;
+		opacity: 0.8;
+		transition: opacity $sa-transition;
+		line-height: 1;
+		padding: 2px 4px;
+
+		&:hover { opacity: 1; }
+
+		&:focus-visible {
+			outline: 2px solid rgba(255, 255, 255, 0.7);
+			border-radius: 4px;
+		}
+	}
+
+	// ── Message body ──────────────────────────────────────────────────────────
+
+	&__body {
+		flex: 1;
+		overflow-y: auto;
+		padding: 14px 12px;
+		display: flex;
+		flex-direction: column;
+		gap: 10px;
+		scroll-behavior: smooth;
+	}
+
+	// ── Footer / input row ────────────────────────────────────────────────────
+
+	&__footer {
+		display: flex;
+		align-items: center;
+		gap: 8px;
+		padding: 10px 12px;
+		border-top: 1px solid $sa-border;
+		flex-shrink: 0;
+	}
+}
+
+// ── Input ────────────────────────────────────────────────────────────────────
+
+.search-agent-input {
+	flex: 1;
+	border: 1px solid $sa-border;
+	border-radius: 20px;
+	padding: 8px 14px;
+	font-size: 14px;
+	color: $sa-text-dark;
+	outline: none;
+	transition: border-color $sa-transition, box-shadow $sa-transition;
+
+	&:focus {
+		border-color: $sa-primary;
+		box-shadow: 0 0 0 3px rgba($sa-primary, 0.15);
+	}
+
+	&:disabled {
+		background-color: #f7f8fa;
+		cursor: not-allowed;
+	}
+}
+
+// ── Send button ────────────────────────────────────────────────────────────────
+
+.search-agent-send {
+	width: 38px;
+	height: 38px;
+	border-radius: 50%;
+	border: none;
+	background-color: $sa-primary;
+	color: $sa-text-light;
+	font-size: 14px;
+	cursor: pointer;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	flex-shrink: 0;
+	transition: background-color $sa-transition, transform $sa-transition;
+
+	&:hover {
+		background-color: $sa-primary-dark;
+	}
+
+	&:active {
+		transform: scale(0.92);
+	}
+
+	&:disabled {
+		background-color: lighten($sa-primary, 25%);
+		cursor: not-allowed;
+	}
+
+	&:focus-visible {
+		outline: 3px solid $sa-primary;
+		outline-offset: 2px;
+	}
+}
+
+// ── Chat bubbles ──────────────────────────────────────────────────────────────
+
+.search-agent-bubble {
+	max-width: 92%;
+	padding: 9px 13px;
+	border-radius: 16px;
+	font-size: 14px;
+	line-height: 1.5;
+	word-wrap: break-word;
+
+	// Bot bubble – left-aligned
+	&--bot {
+		align-self: flex-start;
+		background-color: $sa-bubble-bot-bg;
+		color: $sa-text-dark;
+		border-bottom-left-radius: 4px;
+	}
+
+	// User bubble – right-aligned
+	&--user {
+		align-self: flex-end;
+		background-color: $sa-bubble-user-bg;
+		color: $sa-text-light;
+		border-bottom-right-radius: 4px;
+	}
+
+	// Error state
+	&--error {
+		align-self: flex-start;
+		background-color: $sa-error-bg;
+		border: 1px solid $sa-error-border;
+		color: darken($sa-error-border, 30%);
+		border-bottom-left-radius: 4px;
+	}
+
+	p { margin: 0 0 6px; &:last-child { margin-bottom: 0; } }
+	a { color: $sa-primary; text-decoration: underline; }
+}
+
+// ── Results ordered list ──────────────────────────────────────────────────────
+
+.search-agent-results {
+	margin: 6px 0 0;
+	padding-left: 18px;
+	list-style: decimal;
+
+	li {
+		margin-bottom: 5px;
+		font-size: 13.5px;
+	}
+
+	a {
+		color: $sa-primary;
+		text-decoration: none;
+
+		&:hover { text-decoration: underline; }
+	}
+}
+
+// ── Typing indicator (three bouncing dots) ─────────────────────────────────────
+
+.search-agent-typing {
+	display: inline-flex;
+	align-items: center;
+	gap: 4px;
+	height: 18px;
+
+	span {
+		width: 7px;
+		height: 7px;
+		border-radius: 50%;
+		background-color: darken($sa-bubble-bot-bg, 30%);
+		animation: sa-bounce 1.2s infinite ease-in-out;
+
+		&:nth-child(1) { animation-delay: 0s;    }
+		&:nth-child(2) { animation-delay: 0.2s;  }
+		&:nth-child(3) { animation-delay: 0.4s;  }
+	}
+}
+
+@keyframes sa-bounce {
+	0%, 80%, 100% { transform: scale(0.6); opacity: 0.5; }
+	40%            { transform: scale(1);   opacity: 1;   }
+}
+
+// ── RTL support (Hebrew, Arabic, etc.) ───────────────────────────────────────
+// NodeBB sets `dir="rtl"` on <html> for right-to-left languages.
+
+[dir="rtl"] {
+	.search-agent-wrapper {
+		left: auto;
+		right: $sa-fab-offset-x;
+		align-items: flex-end;
+	}
+
+	.search-agent-panel {
+		transform-origin: bottom right;
+	}
+
+	.search-agent-panel__title {
+		.fa {
+			margin-right: 0;
+			margin-left: 6px;
+		}
+	}
+
+	.search-agent-bubble {
+		// Bot bubble: flip rounded corner to the right side
+		&--bot {
+			border-bottom-left-radius: $sa-border-radius;
+			border-bottom-right-radius: 4px;
+		}
+
+		// User bubble: flip rounded corner to the left side
+		&--user {
+			border-bottom-right-radius: $sa-border-radius;
+			border-bottom-left-radius: 4px;
+		}
+
+		&--error {
+			border-bottom-left-radius: $sa-border-radius;
+			border-bottom-right-radius: 4px;
+		}
+	}
+
+	.search-agent-results {
+		padding-left: 0;
+		padding-right: 18px;
+	}
+}
+

package/static/samplefile.html

@@ -0,0 +1,5 @@
+<h1>Hello!</h1>
+
+<p>This file is served by nodebb at domain.com/assets/plugins/nodebb-plugin-quickstart/static/samplefile.html</p>
+
+Check plugin.json for the "staticDirs" property if you want to change the path.