docusaurus-plugin-glossary 1.1.2 → 1.3.1

package/{remark → lib/remark}/glossary-terms.js

@@ -1,10 +1,10 @@
-const visit = require('unist-util-visit');
-const path = require('path');
-const fs = require('fs');
+import { visit } from 'unist-util-visit';
+import path from 'path';
+import fs from 'fs';
 
 /**
  * Creates a remark plugin that automatically detects and replaces glossary terms in markdown
- * 
+ *
  * @param {object} options - Plugin options
  * @param {Array} options.terms - Array of glossary term objects with {term, definition}
  * @param {string} options.glossaryPath - Path to glossary JSON file (optional, if terms not provided)
@@ -12,11 +12,11 @@ const fs = require('fs');
  * @param {string} options.siteDir - Docusaurus site directory (required if using glossaryPath)
  * @returns {function} Remark plugin function
  */
-function remarkGlossaryTerms({ 
-  terms = [], 
+export default function remarkGlossaryTerms({
+  terms = [],
   glossaryPath = null,
   routePath = '/glossary',
-  siteDir = null
+  siteDir = null,
 } = {}) {
   let glossaryTerms = terms;
 
@@ -44,13 +44,11 @@ function remarkGlossaryTerms({
 
   // Sort terms by length (longest first) to avoid partial matches
   // e.g., "Application Programming Interface" should match before "API"
-  const sortedTerms = Array.from(termMap.entries()).sort(
-    (a, b) => b[0].length - a[0].length
-  );
+  const sortedTerms = Array.from(termMap.entries()).sort((a, b) => b[0].length - a[0].length);
 
   // If no terms, return a no-op transformer
   if (sortedTerms.length === 0) {
-    return (tree) => tree;
+    return tree => tree;
   }
 
   /**
@@ -71,29 +69,50 @@ function remarkGlossaryTerms({
     for (const [lowerTerm, termObj] of sortedTerms) {
       const term = termObj.term;
       let searchIndex = 0;
-      
+
       while (searchIndex < textLower.length) {
         const index = textLower.indexOf(lowerTerm, searchIndex);
         if (index === -1) break;
 
-        // Check if it's a whole word match
+        // Check if it's a whole word match, with simple plural tolerance ('s' or 'es')
         const beforeChar = index > 0 ? textLower[index - 1] : ' ';
-        const afterChar = index + lowerTerm.length < textLower.length 
-          ? textLower[index + lowerTerm.length] 
-          : ' ';
-        
-        // Word boundary check (alphanumeric characters)
-        const isWordBoundary = 
-          !/\w/.test(beforeChar) && !/\w/.test(afterChar);
+        const afterIndex = index + lowerTerm.length;
+        const afterChar = afterIndex < textLower.length ? textLower[afterIndex] : ' ';
+
+        let matchLength = term.length;
+        let isWordBoundary = !/\w/.test(beforeChar) && !/\w/.test(afterChar);
+
+        // Allow trailing 's' plural (e.g., webhook -> webhooks)
+        if (!isWordBoundary && afterChar === 's') {
+          const nextChar = afterIndex + 1 < textLower.length ? textLower[afterIndex + 1] : ' ';
+          if (!/\w/.test(nextChar)) {
+            isWordBoundary = true;
+            matchLength = term.length + 1;
+          }
+        }
+
+        // Allow trailing 'es' plural (e.g., API -> APIs, box -> boxes)
+        if (
+          !isWordBoundary &&
+          afterChar === 'e' &&
+          afterIndex + 1 < textLower.length &&
+          textLower[afterIndex + 1] === 's'
+        ) {
+          const nextChar = afterIndex + 2 < textLower.length ? textLower[afterIndex + 2] : ' ';
+          if (!/\w/.test(nextChar)) {
+            isWordBoundary = true;
+            matchLength = term.length + 2;
+          }
+        }
 
         if (isWordBoundary) {
           matches.push({
             index,
-            length: term.length,
+            length: matchLength,
             term: term,
             termObj: termObj,
             // Store original case from the text
-            originalText: text.substring(index, index + term.length)
+            originalText: text.substring(index, index + matchLength),
           });
         }
 
@@ -120,7 +139,7 @@ function remarkGlossaryTerms({
       if (match.index > lastIndex) {
         result.push({
           type: 'text',
-          value: text.substring(lastIndex, match.index)
+          value: text.substring(lastIndex, match.index),
         });
       }
 
@@ -132,25 +151,25 @@ function remarkGlossaryTerms({
           {
             type: 'mdxJsxAttribute',
             name: 'term',
-            value: match.termObj.term
+            value: match.termObj.term,
           },
           {
             type: 'mdxJsxAttribute',
             name: 'definition',
-            value: match.termObj.definition || ''
+            value: match.termObj.definition || '',
           },
           {
             type: 'mdxJsxAttribute',
             name: 'routePath',
-            value: routePath
-          }
+            value: routePath,
+          },
         ],
         children: [
           {
             type: 'text',
-            value: match.originalText
-          }
-        ]
+            value: match.originalText,
+          },
+        ],
       });
 
       lastIndex = match.index + match.length;
@@ -160,14 +179,14 @@ function remarkGlossaryTerms({
     if (lastIndex < text.length) {
       result.push({
         type: 'text',
-        value: text.substring(lastIndex)
+        value: text.substring(lastIndex),
       });
     }
 
     return result.length > 0 ? result : [{ type: 'text', value: text }];
   }
 
-  return (tree) => {
+  return tree => {
     let usedGlossaryTerm = false;
     visit(tree, 'text', (node, index, parent) => {
       // Skip text nodes inside code blocks, links, or existing MDX components
@@ -185,8 +204,10 @@ function remarkGlossaryTerms({
       const replacements = replaceTermsInText(node.value);
 
       // If we have replacements, replace the single text node with multiple nodes
-      if (replacements.length > 1 || 
-          (replacements.length === 1 && replacements[0].type !== 'text')) {
+      if (
+        replacements.length > 1 ||
+        (replacements.length === 1 && replacements[0].type !== 'text')
+      ) {
         // Convert to text elements for paragraph context if needed
         const newNodes = replacements.map(replacement => {
           if (replacement.type === 'mdxJsxFlowElement') {
@@ -196,7 +217,7 @@ function remarkGlossaryTerms({
                 type: 'mdxJsxTextElement',
                 name: replacement.name,
                 attributes: replacement.attributes,
-                children: replacement.children
+                children: replacement.children,
               };
             }
           }
@@ -217,9 +238,11 @@ function remarkGlossaryTerms({
 
     // Inject MDX import for GlossaryTerm if we used it anywhere in this file
     if (usedGlossaryTerm) {
+      // Create import node matching MDX v3 expectations
+      // Both 'value' (the import string) and 'data.estree' (the parsed AST) are required
       const importNode = {
         type: 'mdxjsEsm',
-        value: "import GlossaryTerm from '@theme/GlossaryTerm';",
+        value: "import GlossaryTerm from '@theme/GlossaryTerm'",
         data: {
           estree: {
             type: 'Program',
@@ -230,26 +253,52 @@ function remarkGlossaryTerms({
                 specifiers: [
                   {
                     type: 'ImportDefaultSpecifier',
-                    local: { type: 'Identifier', name: 'GlossaryTerm' }
-                  }
+                    local: { type: 'Identifier', name: 'GlossaryTerm' },
+                  },
                 ],
-                source: { type: 'Literal', value: '@theme/GlossaryTerm' }
-              }
-            ]
-          }
-        }
+                source: {
+                  type: 'Literal',
+                  value: '@theme/GlossaryTerm',
+                  raw: "'@theme/GlossaryTerm'",
+                },
+              },
+            ],
+          },
+        },
       };
 
       // Avoid duplicate imports if already present
-      const hasExistingImport = Array.isArray(tree.children) && tree.children.some(
-        (n) => n.type === 'mdxjsEsm' && typeof n.value === 'string' && n.value.includes("@theme/GlossaryTerm")
-      );
+      const hasExistingImport =
+        Array.isArray(tree.children) &&
+        tree.children.some(n => {
+          if (n.type !== 'mdxjsEsm') return false;
+          // Check value string (for older MDX format)
+          if (typeof n.value === 'string' && n.value.includes('@theme/GlossaryTerm')) {
+            return true;
+          }
+          // Check estree data (for newer MDX format)
+          if (n.data?.estree?.body) {
+            return n.data.estree.body.some(
+              stmt =>
+                stmt.type === 'ImportDeclaration' && stmt.source?.value === '@theme/GlossaryTerm'
+            );
+          }
+          return false;
+        });
+
       if (!hasExistingImport) {
+        // Place import at the very beginning of the file (before all other nodes)
+        // This ensures it's available when MDX compiles the JSX elements
+        if (!Array.isArray(tree.children)) {
+          tree.children = [];
+        }
+        // Insert at the very beginning (index 0) to ensure it's processed first
         tree.children.unshift(importNode);
+        // Debug: verify import was added (remove in production)
+        if (process.env.NODE_ENV !== 'production') {
+          console.log('[glossary-plugin] Injected GlossaryTerm import');
+        }
       }
     }
   };
 }
-
-module.exports = remarkGlossaryTerms;
-

package/lib/theme/GlossaryTerm/index.js

@@ -0,0 +1,130 @@
+import React, { useMemo, useState, useRef, useEffect, useCallback } from 'react';
+import { usePluginData } from '@docusaurus/useGlobalData';
+import styles from './styles.module.css';
+
+/**
+ * GlossaryTerm component - displays an inline term with tooltip
+ *
+ * Usage:
+ * import GlossaryTerm from '@theme/GlossaryTerm';
+ *
+ * <GlossaryTerm term="API" definition="Application Programming Interface" />
+ * or
+ * <GlossaryTerm term="API">custom display text</GlossaryTerm>
+ *
+ * @param {object} props
+ * @param {string} props.term - The glossary term
+ * @param {string} props.definition - The definition to show in tooltip
+ * @param {string} props.routePath - Route path to glossary page (default: '/glossary')
+ * @param {React.ReactNode} props.children - Optional custom display text
+ */
+export default function GlossaryTerm({ term, definition, routePath = '/glossary', children }) {
+  const [showTooltip, setShowTooltip] = useState(false);
+  const [tooltipStyle, setTooltipStyle] = useState(null);
+  const [placement, setPlacement] = useState('top'); // 'top' | 'bottom'
+  const wrapperRef = useRef(null);
+  const tooltipRef = useRef(null);
+
+  const updatePosition = useCallback(() => {
+    if (!wrapperRef.current || !tooltipRef.current) return;
+    const wrapperRect = wrapperRef.current.getBoundingClientRect();
+    const tooltipRect = tooltipRef.current.getBoundingClientRect();
+
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+
+    const preferredGap = 8; // px
+
+    // Decide top vs bottom based on available space
+    const hasSpaceAbove = wrapperRect.top >= tooltipRect.height + preferredGap;
+    const hasSpaceBelow = viewportHeight - wrapperRect.bottom >= tooltipRect.height + preferredGap;
+    const nextPlacement = hasSpaceAbove || !hasSpaceBelow ? 'top' : 'bottom';
+
+    let top;
+    if (nextPlacement === 'top') {
+      top = wrapperRect.top - tooltipRect.height - preferredGap;
+    } else {
+      top = wrapperRect.bottom + preferredGap;
+    }
+
+    // Center horizontally on the wrapper, then clamp within viewport with margin
+    const horizontalMargin = 8;
+    let left = wrapperRect.left + wrapperRect.width / 2 - tooltipRect.width / 2;
+    left = Math.max(
+      horizontalMargin,
+      Math.min(left, viewportWidth - tooltipRect.width - horizontalMargin)
+    );
+
+    setPlacement(nextPlacement);
+    setTooltipStyle({ top: Math.max(4, top), left });
+  }, []);
+
+  useEffect(() => {
+    if (!showTooltip) return;
+    updatePosition();
+    const onScroll = () => updatePosition();
+    const onResize = () => updatePosition();
+    window.addEventListener('scroll', onScroll, true);
+    window.addEventListener('resize', onResize);
+    return () => {
+      window.removeEventListener('scroll', onScroll, true);
+      window.removeEventListener('resize', onResize);
+    };
+  }, [showTooltip, updatePosition]);
+
+  // Pull definition/route from plugin global data if not provided
+  const pluginData = usePluginData('docusaurus-plugin-glossary');
+  const effectiveDefinition = useMemo(() => {
+    if (definition && typeof definition === 'string' && definition.length > 0) {
+      return definition;
+    }
+    const terms = (pluginData && pluginData.terms) || [];
+    const found = terms.find(
+      t => typeof t.term === 'string' && t.term.toLowerCase() === String(term).toLowerCase()
+    );
+    return found && found.definition ? found.definition : undefined;
+  }, [definition, pluginData, term]);
+
+  const effectiveRoutePath = useMemo(() => {
+    if (routePath && typeof routePath === 'string' && routePath.length > 0) return routePath;
+    return (pluginData && pluginData.routePath) || '/glossary';
+  }, [pluginData, routePath]);
+
+  const displayText = children || term;
+  const termId = term.toLowerCase().replace(/\s+/g, '-');
+
+  return (
+    <span ref={wrapperRef} className={styles.glossaryTermWrapper}>
+      <a
+        href={`${effectiveRoutePath}#${termId}`}
+        className={styles.glossaryTerm}
+        onMouseEnter={() => setShowTooltip(true)}
+        onMouseLeave={() => setShowTooltip(false)}
+        onFocus={() => setShowTooltip(true)}
+        onBlur={() => setShowTooltip(false)}
+        aria-describedby={`tooltip-${termId}`}
+      >
+        {displayText}
+      </a>
+      {effectiveDefinition && (
+        <span
+          ref={tooltipRef}
+          id={`tooltip-${termId}`}
+          className={
+            `${styles.tooltip} ${showTooltip ? styles.tooltipVisible : ''} ` +
+            `${placement === 'top' ? styles.tooltipTop : styles.tooltipBottom} ` +
+            `${styles.tooltipFloating}`
+          }
+          role="tooltip"
+          style={
+            showTooltip && tooltipStyle
+              ? { top: `${tooltipStyle.top}px`, left: `${tooltipStyle.left}px` }
+              : undefined
+          }
+        >
+          <strong>{term}:</strong> {effectiveDefinition}
+        </span>
+      )}
+    </span>
+  );
+}

package/{theme → lib/theme}/GlossaryTerm/index.test.js

@@ -113,4 +113,23 @@ describe('GlossaryTerm', () => {
     const tooltip = screen.getByRole('tooltip');
     expect(tooltip).toHaveAttribute('id', 'tooltip-api');
   });
+
+  it('positions tooltip within viewport and adds placement classes', async () => {
+    const user = userEvent.setup();
+    render(<GlossaryTerm term="Edge" definition="Near the boundary of the viewport" />);
+
+    const link = screen.getByRole('link');
+    await user.hover(link);
+
+    const tooltip = screen.getByRole('tooltip');
+    expect(tooltip).toHaveClass('tooltipVisible');
+    expect(tooltip).toHaveClass('tooltipFloating');
+    // One of the placement classes should be present
+    const hasPlacement =
+      tooltip.classList.contains('tooltipTop') || tooltip.classList.contains('tooltipBottom');
+    expect(hasPlacement).toBe(true);
+    // Inline style should include computed top/left
+    expect(tooltip.style.top).toMatch(/px$/);
+    expect(tooltip.style.left).toMatch(/px$/);
+  });
 });

package/{theme → lib/theme}/GlossaryTerm/styles.module.css

@@ -4,17 +4,19 @@
 }
 
 .glossaryTerm {
-  color: var(--ifm-color-primary);
+  color: var(--ifm-font-color-base);
   text-decoration: none;
-  border-bottom: 1px dotted var(--ifm-color-primary);
+  border-bottom: 1px dotted;
+  border-bottom-color: color-mix(in srgb, var(--ifm-font-color-base) 20%, transparent);
   cursor: help;
-  font-weight: 500;
   transition: all 0.2s;
-}
+} 
 
 .glossaryTerm:hover {
   color: var(--ifm-color-primary-dark);
   border-bottom-style: solid;
+  border-bottom-color: var(--ifm-color-primary-dark);
+  border-bottom: none;
 }
 
 .tooltip {
@@ -40,25 +42,55 @@
   visibility: hidden;
 }
 
-.tooltip::after {
+/* When we compute viewport-safe placement via JS */
+.tooltipFloating {
+  position: fixed;
+  bottom: auto;
+  transform: none;
+  left: 0; /* overridden inline */
+  top: 0; /* overridden inline */
+}
+
+/* Base arrow removed; arrows are defined per-placement to avoid inversion */
+
+/* Arrow for top placement (tooltip above anchor) */
+.tooltipTop::after {
   content: '';
   position: absolute;
-  top: 100%;
   left: 50%;
   transform: translateX(-50%);
+  bottom: -6px;
   border: 6px solid transparent;
   border-top-color: var(--ifm-background-surface-color);
 }
-
-.tooltip::before {
+.tooltipTop::before {
   content: '';
   position: absolute;
-  top: 100%;
   left: 50%;
   transform: translateX(-50%);
+  bottom: -7px;
   border: 7px solid transparent;
   border-top-color: var(--ifm-color-emphasis-300);
-  margin-top: 1px;
+}
+
+/* Arrow for bottom placement (tooltip below anchor) */
+.tooltipBottom::after {
+  content: '';
+  position: absolute;
+  left: 50%;
+  transform: translateX(-50%);
+  top: -6px;
+  border: 6px solid transparent;
+  border-bottom-color: var(--ifm-background-surface-color);
+}
+.tooltipBottom::before {
+  content: '';
+  position: absolute;
+  left: 50%;
+  transform: translateX(-50%);
+  top: -7px;
+  border: 7px solid transparent;
+  border-bottom-color: var(--ifm-color-emphasis-300);
 }
 
 .tooltipVisible {
@@ -79,13 +111,19 @@
   border-color: var(--ifm-color-emphasis-400);
 }
 
-[data-theme='dark'] .tooltip::after {
+/* Dark mode arrow overrides scoped to placement to avoid upside-down arrows */
+[data-theme='dark'] .tooltipTop::after {
   border-top-color: var(--ifm-background-surface-color);
 }
-
-[data-theme='dark'] .tooltip::before {
+[data-theme='dark'] .tooltipTop::before {
   border-top-color: var(--ifm-color-emphasis-400);
 }
+[data-theme='dark'] .tooltipBottom::after {
+  border-bottom-color: var(--ifm-background-surface-color);
+}
+[data-theme='dark'] .tooltipBottom::before {
+  border-bottom-color: var(--ifm-color-emphasis-400);
+}
 
 /* Responsive adjustments */
 @media (max-width: 768px) {

package/package.json

@@ -1,24 +1,31 @@
 {
   "name": "docusaurus-plugin-glossary",
-  "version": "1.1.2",
+  "version": "1.3.1",
   "description": "A Docusaurus plugin for creating and managing glossary terms with auto-generated pages and inline tooltips",
-  "main": "index.js",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "import": "./lib/index.js"
+    },
+    "./remark/glossary-terms": "./lib/remark/glossary-terms.js"
+  },
   "files": [
-    "index.js",
-    "components/",
-    "theme/",
-    "remark/",
+    "lib/",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
+    "build": "tsc && node scripts/build.js",
+    "watch": "node scripts/watch.js",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
     "example:start": "npm --prefix examples/docusaurus-v3 run start",
     "example:build": "npm --prefix examples/docusaurus-v3 run build",
     "example:serve": "npm --prefix examples/docusaurus-v3 run serve",
-    "prepublishOnly": "npm test",
+    "example:clear": "npm --prefix examples/docusaurus-v3 run clear",
+    "prepublishOnly": "npm run build && npm test",
     "version": "npm version",
     "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,css,md}\"",
     "format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,json,css,md}\""
@@ -49,7 +56,8 @@
   },
   "dependencies": {
     "fs-extra": "^11.0.0",
-    "unist-util-visit": "^5.0.0"
+    "unist-util-visit": "^5.0.0",
+    "validate-peer-dependencies": "^2.2.0"
   },
   "engines": {
     "node": ">=16.14"
@@ -57,6 +65,8 @@
   "devDependencies": {
     "@babel/preset-env": "^7.28.5",
     "@babel/preset-react": "^7.28.5",
+    "@docusaurus/tsconfig": "^3.9.2",
+    "@docusaurus/types": "^3.9.2",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
@@ -64,6 +74,19 @@
     "identity-obj-proxy": "^3.0.0",
     "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.2.0",
-    "prettier": "^3.6.2"
+    "prettier": "^3.6.2",
+    "typescript": "^5.7.3"
+  },
+  "browser": {
+    "path": false,
+    "url": false,
+    "fs": false,
+    "fs-extra": false,
+    "graceful-fs": false,
+    "jsonfile": false,
+    "util": false,
+    "assert": false,
+    "stream": false,
+    "constants": false
   }
 }