docusaurus-plugin-glossary 3.3.3 → 3.3.4

package/dist/types-B6LWPlBY.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared type definitions for docusaurus-plugin-glossary.
+ *
+ * Single source of truth for the *declared* public data shapes. Both the plugin
+ * entry point (`src/index.ts`) and the remark plugin declaration
+ * (`src/remark/glossary-terms.d.ts`) consume these, so the declarations can't
+ * drift from each other.
+ *
+ * Note: the remark runtime (`src/remark/glossary-terms.js`) is plain JS with
+ * `checkJs: false`, so it is NOT type-checked against these shapes — keep it in
+ * sync by hand.
+ */
+/** A single glossary entry. */
+interface GlossaryTerm {
+    term: string;
+    definition: string;
+    abbreviation?: string;
+    relatedTerms?: string[];
+    id?: string;
+    autoLink?: boolean;
+    aliases?: string[];
+    caseSensitive?: boolean;
+}
+/** Shape of a glossary JSON file. */
+interface GlossaryData {
+    title?: string;
+    description?: string;
+    terms: GlossaryTerm[];
+}
+/** Options accepted by the glossary plugin / preset. */
+interface GlossaryPluginOptions {
+    glossaryPath?: string;
+    routePath?: string;
+    autoLinkTerms?: boolean;
+    /**
+     * When true, the first canonical occurrence of any term that has an `abbreviation` is
+     * rendered as "Long Form (Term)" instead of just "Term", enforcing the convention of
+     * introducing an acronym on first use. Subsequent occurrences in the same file render
+     * normally. Default: false.
+     */
+    expandAcronymsOnFirstUse?: boolean;
+}
+/** Options accepted by the `remark/glossary-terms` plugin. */
+interface RemarkGlossaryTermsOptions {
+    terms?: GlossaryTerm[];
+    glossaryPath?: string | null;
+    routePath?: string;
+    siteDir?: string | null;
+    expandAcronymsOnFirstUse?: boolean;
+}
+/** The transformer returned by the remark plugin factory. */
+type RemarkGlossaryTermsTransformer = (tree: unknown) => unknown;
+
+export type { GlossaryPluginOptions as G, RemarkGlossaryTermsOptions as R, GlossaryData as a, GlossaryTerm as b, RemarkGlossaryTermsTransformer as c };

package/dist/validation.d.cts

@@ -1,2 +1,46 @@
-export { GlossaryValidationError, ValidationError, ValidationResult, formatValidationErrors, validateGlossaryData } from './index.cjs';
-import '@docusaurus/types';
+import { a as GlossaryData } from './types-B6LWPlBY.cjs';
+
+interface ValidationError {
+    field: string;
+    message: string;
+    value?: unknown;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    data: GlossaryData;
+}
+/**
+ * Validates glossary data structure
+ *
+ * Ensures the glossary data conforms to the expected schema:
+ * - Must be an object with a "terms" array
+ * - Each term must have "term" (string) and "definition" (string)
+ * - Optional fields: abbreviation (string), relatedTerms (string[]), id (string)
+ *
+ * @param data - The data to validate
+ * @param options - Validation options
+ * @param options.throwOnError - If true, throws an error on validation failure (default: true)
+ * @returns Validation result with errors and sanitized data
+ * @throws Error if data is invalid and throwOnError is true
+ */
+declare function validateGlossaryData(data: unknown, options?: {
+    throwOnError?: boolean;
+}): ValidationResult;
+/**
+ * Custom error class for glossary validation errors
+ * Provides detailed error messages for debugging
+ */
+declare class GlossaryValidationError extends Error {
+    readonly errors: ValidationError[];
+    constructor(errors: ValidationError[]);
+}
+/**
+ * Formats validation errors into a readable string
+ *
+ * @param errors - Array of validation errors
+ * @returns Formatted error message
+ */
+declare function formatValidationErrors(errors: ValidationError[]): string;
+
+export { GlossaryValidationError, type ValidationError, type ValidationResult, formatValidationErrors, validateGlossaryData };

package/dist/validation.d.ts

@@ -1,2 +1,46 @@
-export { GlossaryValidationError, ValidationError, ValidationResult, formatValidationErrors, validateGlossaryData } from './index.js';
-import '@docusaurus/types';
+import { a as GlossaryData } from './types-B6LWPlBY.js';
+
+interface ValidationError {
+    field: string;
+    message: string;
+    value?: unknown;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    data: GlossaryData;
+}
+/**
+ * Validates glossary data structure
+ *
+ * Ensures the glossary data conforms to the expected schema:
+ * - Must be an object with a "terms" array
+ * - Each term must have "term" (string) and "definition" (string)
+ * - Optional fields: abbreviation (string), relatedTerms (string[]), id (string)
+ *
+ * @param data - The data to validate
+ * @param options - Validation options
+ * @param options.throwOnError - If true, throws an error on validation failure (default: true)
+ * @returns Validation result with errors and sanitized data
+ * @throws Error if data is invalid and throwOnError is true
+ */
+declare function validateGlossaryData(data: unknown, options?: {
+    throwOnError?: boolean;
+}): ValidationResult;
+/**
+ * Custom error class for glossary validation errors
+ * Provides detailed error messages for debugging
+ */
+declare class GlossaryValidationError extends Error {
+    readonly errors: ValidationError[];
+    constructor(errors: ValidationError[]);
+}
+/**
+ * Formats validation errors into a readable string
+ *
+ * @param errors - Array of validation errors
+ * @returns Formatted error message
+ */
+declare function formatValidationErrors(errors: ValidationError[]): string;
+
+export { GlossaryValidationError, type ValidationError, type ValidationResult, formatValidationErrors, validateGlossaryData };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-glossary",
-  "version": "3.3.3",
+  "version": "3.3.4",
   "description": "A Docusaurus plugin for creating and managing glossary terms with auto-generated pages and inline tooltips",
   "type": "module",
   "main": "dist/index.cjs",
@@ -8,19 +8,34 @@
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./preset": {
-      "types": "./dist/preset.d.ts",
-      "import": "./dist/preset.js",
-      "require": "./dist/preset.cjs"
+      "import": {
+        "types": "./dist/preset.d.ts",
+        "default": "./dist/preset.js"
+      },
+      "require": {
+        "types": "./dist/preset.d.cts",
+        "default": "./dist/preset.cjs"
+      }
     },
     "./remark/glossary-terms": {
-      "types": "./dist/remark/glossary-terms.d.ts",
-      "import": "./dist/remark/glossary-terms.js",
-      "require": "./dist/remark/glossary-terms.cjs"
+      "import": {
+        "types": "./dist/remark/glossary-terms.d.ts",
+        "default": "./dist/remark/glossary-terms.js"
+      },
+      "require": {
+        "types": "./dist/remark/glossary-terms.d.cts",
+        "default": "./dist/remark/glossary-terms.cjs"
+      }
     }
   },
   "files": [
@@ -34,6 +49,7 @@
     "watch": "npm run dev",
     "clean": "rimraf dist",
     "typecheck": "tsc --noEmit",
+    "check:exports": "npm run build && attw --pack --profile node16 .",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
@@ -44,7 +60,7 @@
     "example:serve": "npm --prefix examples/docusaurus-v3 run serve",
     "example:clear": "npm --prefix examples/docusaurus-v3 run clear",
     "prepare": "husky",
-    "prepublishOnly": "npm run build && npm test",
+    "prepublishOnly": "npm run build && npm test && npm run check:exports",
     "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,css,md}\"",
     "format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,json,css,md}\"",
     "lint": "eslint \"src/**/*.{js,jsx,ts,tsx}\" \"__tests__/**/*.js\"",
@@ -80,9 +96,10 @@
     "validate-peer-dependencies": "^2.2.0"
   },
   "engines": {
-    "node": ">=18.0"
+    "node": ">=20.0"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.4",
     "@babel/preset-env": "^7.28.5",
     "@babel/preset-react": "^7.28.5",
     "@babel/preset-typescript": "^7.28.5",

package/dist/chunk-TIO6T3VD.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @ts-ignore\nimport path from 'path';\n// @ts-ignore\nimport { fileURLToPath } from 'url';\nimport fs from 'fs-extra';\nimport type { LoadContext, Plugin } from '@docusaurus/types';\nimport validatePeerDependencies from 'validate-peer-dependencies';\nimport remarkGlossaryTerms from './remark/glossary-terms.js';\nimport { validateGlossaryData, GlossaryValidationError } from './validation.js';\n\n// Standard ES module directory resolution\nconst currentFilePath = fileURLToPath(import.meta.url);\nconst currentDir = path.dirname(currentFilePath);\n\n// Validate peer dependencies at module load time\nvalidatePeerDependencies(currentDir);\n\nexport interface GlossaryPluginOptions {\n  glossaryPath?: string;\n  routePath?: string;\n  autoLinkTerms?: boolean;\n  /**\n   * When true, the first canonical occurrence of any term that has an `abbreviation` is\n   * rendered as \"Long Form (Term)\" instead of just \"Term\", enforcing the convention of\n   * introducing an acronym on first use. Subsequent occurrences in the same file render\n   * normally. Default: false.\n   */\n  expandAcronymsOnFirstUse?: boolean;\n}\n\nexport interface GlossaryTerm {\n  term: string;\n  definition: string;\n  abbreviation?: string;\n  relatedTerms?: string[];\n  id?: string;\n  autoLink?: boolean;\n  aliases?: string[];\n  caseSensitive?: boolean;\n}\n\nexport interface GlossaryData {\n  title?: string;\n  description?: string;\n  terms: GlossaryTerm[];\n}\n\n/**\n * Docusaurus Glossary Plugin\n *\n * A plugin that provides glossary functionality with:\n * - Glossary terms defined in a JSON file\n * - Auto-generated glossary page with term definitions\n * - GlossaryTerm component for inline definitions with interactive tooltips\n * - Automatic client-side initialization via getClientModules() (no manual imports needed)\n * - Optional automatic glossary term detection in markdown files via remark plugin\n *\n * ## Basic Usage (Manual Term Markup)\n *\n * Just install the plugin - the GlossaryTerm component is automatically available:\n * ```javascript\n * module.exports = {\n *   plugins: [\n *     ['docusaurus-plugin-glossary', {\n *       glossaryPath: 'glossary/glossary.json',\n *       routePath: '/glossary',\n *     }],\n *   ],\n * };\n * ```\n *\n * Then use `<GlossaryTerm>` in your MDX files without importing:\n * ```mdx\n * <GlossaryTerm term=\"API\">API</GlossaryTerm>\n * ```\n *\n * ## Advanced Usage (Automatic Term Detection)\n *\n * To automatically detect and link glossary terms in markdown, add the remark plugin:\n * ```javascript\n * const glossaryPlugin = require('docusaurus-plugin-glossary');\n *\n * module.exports = {\n *   presets: [\n *     ['@docusaurus/preset-classic', {\n *       docs: {\n *         remarkPlugins: [\n *           glossaryPlugin.getRemarkPlugin({\n *             glossaryPath: 'glossary/glossary.json',\n *             routePath: '/glossary',\n *           }, { siteDir: __dirname }),\n *         ],\n *       },\n *     }],\n *   ],\n *   plugins: [\n *     ['docusaurus-plugin-glossary', {\n *       glossaryPath: 'glossary/glossary.json',\n *       routePath: '/glossary',\n *     }],\n *   ],\n * };\n * ```\n *\n * @param context - Docusaurus context\n * @param options - Plugin options\n * @param options.glossaryPath - Path to glossary JSON file (default: 'glossary/glossary.json')\n * @param options.routePath - Route path for glossary page (default: '/glossary')\n * @param options.autoLinkTerms - Legacy option, kept for compatibility but no longer used (configure remark plugin manually instead)\n * @returns Plugin object\n */\nexport default function glossaryPlugin(\n  context: LoadContext,\n  options: GlossaryPluginOptions = {}\n): Plugin {\n  const { glossaryPath = 'glossary/glossary.json', routePath = '/glossary' } = options;\n\n  return {\n    name: 'docusaurus-plugin-glossary',\n\n    getClientModules() {\n      return [path.resolve(currentDir, './client/index.js')];\n    },\n\n    async loadContent() {\n      // Load glossary terms from JSON file\n      const glossaryFilePath = path.resolve(context.siteDir, glossaryPath);\n\n      if (await fs.pathExists(glossaryFilePath)) {\n        try {\n          const rawData = await fs.readJson(glossaryFilePath);\n\n          // Validate glossary data structure\n          const validationResult = validateGlossaryData(rawData, { throwOnError: false });\n\n          if (!validationResult.valid) {\n            console.warn(\n              `[glossary-plugin] Glossary file has validation errors at ${glossaryFilePath}:`\n            );\n            validationResult.errors.forEach(err => {\n              console.warn(`  - [${err.field}] ${err.message}`);\n            });\n            console.warn('[glossary-plugin] Proceeding with valid terms only.');\n          }\n\n          return validationResult.data;\n        } catch (error) {\n          if (error instanceof GlossaryValidationError) {\n            throw error;\n          }\n          // JSON parsing error\n          throw new Error(\n            `Failed to parse glossary file at ${glossaryFilePath}: ${error instanceof Error ? error.message : String(error)}`\n          );\n        }\n      }\n\n      console.warn(`Glossary file not found at ${glossaryFilePath}. Using empty glossary.`);\n      return { terms: [] };\n    },\n\n    async contentLoaded({ content, actions }) {\n      const { createData, addRoute, setGlobalData } = actions;\n      const glossaryContent = content as GlossaryData;\n\n      // Create data file that can be imported by components\n      const glossaryDataPath = await createData(\n        'glossary-data.json',\n        JSON.stringify(glossaryContent)\n      );\n\n      // Create a data file for the remark plugin to access glossary terms\n      await createData(\n        'remark-glossary-data.json',\n        JSON.stringify({\n          terms: glossaryContent.terms || [],\n          routePath: routePath,\n        })\n      );\n\n      // Add glossary page route\n      addRoute({\n        path: routePath,\n        component: path.join(currentDir, 'components/GlossaryPage.js'),\n        exact: true,\n        modules: {\n          glossaryData: glossaryDataPath,\n        },\n      });\n\n      // Expose global data for runtime lookups (used by GlossaryTerm)\n      setGlobalData({\n        terms: glossaryContent.terms || [],\n        routePath,\n      });\n    },\n\n    getThemePath() {\n      return path.resolve(currentDir, './theme');\n    },\n\n    getPathsToWatch() {\n      return [path.resolve(context.siteDir, glossaryPath)];\n    },\n\n    async postBuild() {\n      // You can add any post-build steps here if needed\n      console.log('Glossary plugin: Build completed');\n    },\n  };\n}\n\n// Export remark plugin factory for use in markdown configuration\nexport const remarkPlugin = remarkGlossaryTerms;\n\n// Export cache clearing utility\nexport { clearGlossaryCache } from './remark/glossary-terms.js';\n\n// Export validation utilities\nexport {\n  validateGlossaryData,\n  GlossaryValidationError,\n  formatValidationErrors,\n  type ValidationError,\n  type ValidationResult,\n} from './validation.js';\n\n/**\n * Helper function to get the configured remark plugin\n * This can be used in docusaurus.config.js markdown configuration\n *\n * @param pluginOptions - Plugin options from docusaurus.config.js\n * @param context - Context with siteDir\n * @returns Configured remark plugin\n */\nexport function getRemarkPlugin(\n  pluginOptions: GlossaryPluginOptions,\n  context?: { siteDir?: string }\n): [\n  typeof remarkGlossaryTerms,\n  {\n    glossaryPath: string;\n    routePath: string;\n    siteDir?: string;\n    expandAcronymsOnFirstUse: boolean;\n  },\n] {\n  const {\n    glossaryPath = 'glossary/glossary.json',\n    routePath = '/glossary',\n    expandAcronymsOnFirstUse = false,\n  } = pluginOptions;\n\n  const siteDir = context?.siteDir;\n\n  return [\n    remarkGlossaryTerms,\n    {\n      glossaryPath,\n      routePath,\n      siteDir,\n      expandAcronymsOnFirstUse,\n    },\n  ];\n}\n"],"mappings":";;;;;;;;;AACA,OAAO,UAAU;AAEjB,SAAS,qBAAqB;AAC9B,OAAO,QAAQ;AAEf,OAAO,8BAA8B;AAKrC,IAAM,kBAAkB,cAAc,YAAY,GAAG;AACrD,IAAM,aAAa,KAAK,QAAQ,eAAe;AAG/C,yBAAyB,UAAU;AAgGpB,SAAR,eACL,SACA,UAAiC,CAAC,GAC1B;AACR,QAAM,EAAE,eAAe,0BAA0B,YAAY,YAAY,IAAI;AAE7E,SAAO;AAAA,IACL,MAAM;AAAA,IAEN,mBAAmB;AACjB,aAAO,CAAC,KAAK,QAAQ,YAAY,mBAAmB,CAAC;AAAA,IACvD;AAAA,IAEA,MAAM,cAAc;AAElB,YAAM,mBAAmB,KAAK,QAAQ,QAAQ,SAAS,YAAY;AAEnE,UAAI,MAAM,GAAG,WAAW,gBAAgB,GAAG;AACzC,YAAI;AACF,gBAAM,UAAU,MAAM,GAAG,SAAS,gBAAgB;AAGlD,gBAAM,mBAAmB,qBAAqB,SAAS,EAAE,cAAc,MAAM,CAAC;AAE9E,cAAI,CAAC,iBAAiB,OAAO;AAC3B,oBAAQ;AAAA,cACN,4DAA4D,gBAAgB;AAAA,YAC9E;AACA,6BAAiB,OAAO,QAAQ,SAAO;AACrC,sBAAQ,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,OAAO,EAAE;AAAA,YAClD,CAAC;AACD,oBAAQ,KAAK,qDAAqD;AAAA,UACpE;AAEA,iBAAO,iBAAiB;AAAA,QAC1B,SAAS,OAAO;AACd,cAAI,iBAAiB,yBAAyB;AAC5C,kBAAM;AAAA,UACR;AAEA,gBAAM,IAAI;AAAA,YACR,oCAAoC,gBAAgB,KAAK,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC;AAAA,UACjH;AAAA,QACF;AAAA,MACF;AAEA,cAAQ,KAAK,8BAA8B,gBAAgB,yBAAyB;AACpF,aAAO,EAAE,OAAO,CAAC,EAAE;AAAA,IACrB;AAAA,IAEA,MAAM,cAAc,EAAE,SAAS,QAAQ,GAAG;AACxC,YAAM,EAAE,YAAY,UAAU,cAAc,IAAI;AAChD,YAAM,kBAAkB;AAGxB,YAAM,mBAAmB,MAAM;AAAA,QAC7B;AAAA,QACA,KAAK,UAAU,eAAe;AAAA,MAChC;AAGA,YAAM;AAAA,QACJ;AAAA,QACA,KAAK,UAAU;AAAA,UACb,OAAO,gBAAgB,SAAS,CAAC;AAAA,UACjC;AAAA,QACF,CAAC;AAAA,MACH;AAGA,eAAS;AAAA,QACP,MAAM;AAAA,QACN,WAAW,KAAK,KAAK,YAAY,4BAA4B;AAAA,QAC7D,OAAO;AAAA,QACP,SAAS;AAAA,UACP,cAAc;AAAA,QAChB;AAAA,MACF,CAAC;AAGD,oBAAc;AAAA,QACZ,OAAO,gBAAgB,SAAS,CAAC;AAAA,QACjC;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IAEA,eAAe;AACb,aAAO,KAAK,QAAQ,YAAY,SAAS;AAAA,IAC3C;AAAA,IAEA,kBAAkB;AAChB,aAAO,CAAC,KAAK,QAAQ,QAAQ,SAAS,YAAY,CAAC;AAAA,IACrD;AAAA,IAEA,MAAM,YAAY;AAEhB,cAAQ,IAAI,kCAAkC;AAAA,IAChD;AAAA,EACF;AACF;AAGO,IAAM,eAAe;AAsBrB,SAAS,gBACd,eACA,SASA;AACA,QAAM;AAAA,IACJ,eAAe;AAAA,IACf,YAAY;AAAA,IACZ,2BAA2B;AAAA,EAC7B,IAAI;AAEJ,QAAM,UAAU,SAAS;AAEzB,SAAO;AAAA,IACL;AAAA,IACA;AAAA,MACE;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;","names":[]}