@wdprlib/parser 4.1.0 → 4.2.0

package/src/parser/rules/block/module/resolution/dynamic-modules.ts

@@ -1,19 +1,23 @@
 import type { Element } from "@wdprlib/ast";
 import { isListPagesModule, resolveListPages } from "../listpages/resolve";
 import { isListUsersModule, resolveListUsers } from "../listusers/resolve";
+import { isTagCloudModule, resolveTagCloud } from "../tagcloud/resolve";
 import { walkElements } from "../walk";
-import type { ListPagesContext, ListUsersContext } from "./contexts";
+import type { ListPagesContext, ListUsersContext, TagCloudContext } from "./contexts";
 
 export interface DynamicModuleContext {
   listPages: ListPagesContext | null;
   listUsers: ListUsersContext | null;
+  tagCloud: TagCloudContext | null;
   fetchListPagesProvided: boolean;
   fetchListUsersProvided: boolean;
+  fetchTagCloudProvided: boolean;
 }
 
 export interface DynamicModuleIds {
   listPagesId: number;
   listUsersId: number;
+  tagCloudId: number;
 }
 
 export interface DynamicModuleResolution {
@@ -75,11 +79,32 @@ export function resolveDynamicModuleElement(
     };
   }
 
+  if (isTagCloudModule(element.data)) {
+    const elements: Element[] = [];
+    const tagCloudId = ids.tagCloudId;
+
+    if (ctx.tagCloud) {
+      const moduleData = ctx.tagCloud.dataMap.get(tagCloudId);
+
+      if (moduleData) {
+        elements.push(...resolveTagCloud(element.data, moduleData));
+      }
+    } else if (!ctx.fetchTagCloudProvided) {
+      elements.push(element);
+    }
+
+    return {
+      handled: true,
+      elements,
+      ids: { ...ids, tagCloudId: tagCloudId + 1 },
+    };
+  }
+
   return { handled: false, elements: [element], ids };
 }
 
 export function countDynamicModules(elements: Element[]): DynamicModuleIds {
-  const counts: DynamicModuleIds = { listPagesId: 0, listUsersId: 0 };
+  const counts: DynamicModuleIds = { listPagesId: 0, listUsersId: 0, tagCloudId: 0 };
   walkElements(elements, (element) => {
     if (element.element !== "module") return;
 
@@ -87,6 +112,8 @@ export function countDynamicModules(elements: Element[]): DynamicModuleIds {
       counts.listPagesId++;
     } else if (isListUsersModule(element.data)) {
       counts.listUsersId++;
+    } else if (isTagCloudModule(element.data)) {
+      counts.tagCloudId++;
     }
   });
   return counts;

package/src/parser/rules/block/module/resolution/walk-resolve.ts

@@ -1,7 +1,7 @@
 import type { Element } from "@wdprlib/ast";
 import { mapElementChildrenWithState } from "../walk";
 import { isIfTagsElement, resolveIfTags, type IfTagsData } from "../iftags/resolve";
-import type { ListPagesContext, ListUsersContext } from "./contexts";
+import type { ListPagesContext, ListUsersContext, TagCloudContext } from "./contexts";
 import { countDynamicModules, resolveDynamicModuleElement } from "./dynamic-modules";
 
 /**
@@ -10,19 +10,24 @@ import { countDynamicModules, resolveDynamicModuleElement } from "./dynamic-modu
 export interface WalkContext {
   listPages: ListPagesContext | null;
   listUsers: ListUsersContext | null;
+  tagCloud: TagCloudContext | null;
   /** Whether fetchListPages callback was provided, even if no data returned. */
   fetchListPagesProvided: boolean;
   /** Whether fetchListUsers callback was provided, even if no data returned. */
   fetchListUsersProvided: boolean;
+  /** Whether fetchTagCloud callback was provided, even if no data returned. */
+  fetchTagCloudProvided: boolean;
   pageTags: string[] | null;
   listPagesIdCounter: number;
   listUsersIdCounter: number;
+  tagCloudIdCounter: number;
 }
 
 export interface WalkResult {
   elements: Element[];
   nextListPagesId: number;
   nextListUsersId: number;
+  nextTagCloudId: number;
 }
 
 /**
@@ -32,13 +37,19 @@ export function walkAndResolve(elements: Element[], ctx: WalkContext): WalkResul
   const result: Element[] = [];
   let listPagesId = ctx.listPagesIdCounter;
   let listUsersId = ctx.listUsersIdCounter;
+  let tagCloudId = ctx.tagCloudIdCounter;
 
   for (const element of elements) {
-    const dynamicModule = resolveDynamicModuleElement(element, ctx, { listPagesId, listUsersId });
+    const dynamicModule = resolveDynamicModuleElement(element, ctx, {
+      listPagesId,
+      listUsersId,
+      tagCloudId,
+    });
     if (dynamicModule.handled) {
       result.push(...dynamicModule.elements);
       listPagesId = dynamicModule.ids.listPagesId;
       listUsersId = dynamicModule.ids.listUsersId;
+      tagCloudId = dynamicModule.ids.tagCloudId;
       continue;
     }
 
@@ -52,20 +63,24 @@ export function walkAndResolve(elements: Element[], ctx: WalkContext): WalkResul
             ...ctx,
             listPagesIdCounter: listPagesId,
             listUsersIdCounter: listUsersId,
+            tagCloudIdCounter: tagCloudId,
           });
           result.push(...childResult.elements);
           listPagesId = childResult.nextListPagesId;
           listUsersId = childResult.nextListUsersId;
+          tagCloudId = childResult.nextTagCloudId;
         } else {
           const counts = countDynamicModules(ifTagsData.elements);
           listPagesId += counts.listPagesId;
           listUsersId += counts.listUsersId;
+          tagCloudId += counts.tagCloudId;
         }
       } else {
         const childResult = walkAndResolve(ifTagsData.elements, {
           ...ctx,
           listPagesIdCounter: listPagesId,
           listUsersIdCounter: listUsersId,
+          tagCloudIdCounter: tagCloudId,
         });
         result.push({
           element: "if-tags",
@@ -76,24 +91,27 @@ export function walkAndResolve(elements: Element[], ctx: WalkContext): WalkResul
         });
         listPagesId = childResult.nextListPagesId;
         listUsersId = childResult.nextListUsersId;
+        tagCloudId = childResult.nextTagCloudId;
       }
       continue;
     }
 
     const mapped = mapElementChildrenWithState(
       element,
-      { listPagesId, listUsersId },
+      { listPagesId, listUsersId, tagCloudId },
       (children, state) => {
         const childResult = walkAndResolve(children, {
           ...ctx,
           listPagesIdCounter: state.listPagesId,
           listUsersIdCounter: state.listUsersId,
+          tagCloudIdCounter: state.tagCloudId,
         });
         return {
           elements: childResult.elements,
           state: {
             listPagesId: childResult.nextListPagesId,
             listUsersId: childResult.nextListUsersId,
+            tagCloudId: childResult.nextTagCloudId,
           },
         };
       },
@@ -101,7 +119,13 @@ export function walkAndResolve(elements: Element[], ctx: WalkContext): WalkResul
     result.push(mapped.element);
     listPagesId = mapped.state.listPagesId;
     listUsersId = mapped.state.listUsersId;
+    tagCloudId = mapped.state.tagCloudId;
   }
 
-  return { elements: result, nextListPagesId: listPagesId, nextListUsersId: listUsersId };
+  return {
+    elements: result,
+    nextListPagesId: listPagesId,
+    nextListUsersId: listUsersId,
+    nextTagCloudId: tagCloudId,
+  };
 }

package/src/parser/rules/block/module/resolve.ts

@@ -21,8 +21,13 @@ import type { DataProvider } from "./types-common";
 import { resolveIncludes } from "./include";
 import type { ListPagesDataRequirement, CompiledTemplate } from "./listpages/types";
 import type { ListUsersDataRequirement, ListUsersCompiledTemplate } from "./listusers/types";
+import type { TagCloudDataRequirement } from "./tagcloud/types";
 import type { ParseFunction } from "./listpages/resolve";
-import { buildListPagesContext, buildListUsersContext } from "./resolution/contexts";
+import {
+  buildListPagesContext,
+  buildListUsersContext,
+  buildTagCloudContext,
+} from "./resolution/contexts";
 import { walkAndResolve } from "./resolution/walk-resolve";
 import { collectStyles } from "./resolution/styles";
 
@@ -71,6 +76,7 @@ export interface ResolveOptions {
   requirements: {
     listPages?: ListPagesDataRequirement[];
     listUsers?: ListUsersDataRequirement[];
+    tagCloud?: TagCloudDataRequirement[];
   };
 
   /**
@@ -139,17 +145,21 @@ export async function resolveModules(
     options.compiledListUsersTemplates,
     parse,
   );
+  const tagCloudCtx = await buildTagCloudContext(dataProvider, options.requirements.tagCloud ?? []);
   const pageTags = dataProvider.getPageTags?.() ?? null;
 
   // Resolve AST
   const resolvedElements = walkAndResolve(ast.elements, {
     listPages: listPagesCtx,
     listUsers: listUsersCtx,
+    tagCloud: tagCloudCtx,
     fetchListPagesProvided: dataProvider.fetchListPages !== undefined,
     fetchListUsersProvided: dataProvider.fetchListUsers !== undefined,
+    fetchTagCloudProvided: dataProvider.fetchTagCloud !== undefined,
     pageTags,
     listPagesIdCounter: 0,
     listUsersIdCounter: 0,
+    tagCloudIdCounter: 0,
   });
 
   // Collect style elements from resolved AST

package/src/parser/rules/block/module/tagcloud/index.ts

@@ -0,0 +1,15 @@
+/**
+ *
+ * Barrel exports for the TagCloud module.
+ *
+ * @module
+ */
+
+export { tagCloudModuleRule } from "./parser";
+export { isTagCloudModule, resolveTagCloud, type TagCloudModuleData } from "./resolve";
+export type {
+  TagCloudDataFetcher,
+  TagCloudDataRequirement,
+  TagCloudExternalData,
+  TagCloudTagData,
+} from "./types";

package/src/parser/rules/block/module/tagcloud/parser.ts

@@ -0,0 +1,127 @@
+/**
+ *
+ * Parser rule for the Wikidot `[[module TagCloud]]` block.
+ *
+ * Parses font size, color, target, limit, and category attributes into a
+ * `tag-cloud` Module AST node, mirroring the validation behavior of Wikidot's
+ * `PagesTagCloudModule`. Invalid font size or color formats produce an error
+ * block element, matching Wikidot's ProcessException messages.
+ *
+ * @module
+ */
+
+import { CSS_LENGTH_UNITS, type CssLengthUnit, type Element, type Module } from "@wdprlib/ast";
+import type { ModuleRule } from "../types";
+
+/**
+ * Matches a font size value like `300%`, `2em`, or `16px`.
+ *
+ * Wikidot only accepts `px`, `em`, and `%` here; wdpr deliberately extends
+ * this to all CSS length units (see `CSS_LENGTH_UNITS`), case-insensitively.
+ */
+const FONT_SIZE_PATTERN = new RegExp(`^([0-9]+)(${CSS_LENGTH_UNITS.join("|")})$`, "i");
+
+/** Matches a color value like `64,64,128` (range is not enforced, per Wikidot). */
+const COLOR_PATTERN = /^[0-9]+,[0-9]+,[0-9]+$/;
+
+/** Matches a strictly positive integer, mirroring PHP's `is_numeric` + `> 0` gate. */
+const POSITIVE_INT_PATTERN = /^[0-9]+$/;
+
+const ERROR_FONT_FORMAT =
+  "Unsupported format for font size. Use a number followed by a CSS length unit such as px, em or %.";
+const ERROR_FONT_MISMATCH = "Format for minFontSize and maxFontSize must use the same unit.";
+const ERROR_COLOR_FORMAT =
+  'Unsupported color format. Use "RRR,GGG,BBB" for Red,Green,Blue each within 0-255 range.';
+
+/** Build the Wikidot-compatible error block for invalid attribute values. */
+function errorBlock(message: string): Element {
+  return {
+    element: "container",
+    data: {
+      type: "div",
+      attributes: { class: "error-block" },
+      elements: [{ element: "text", data: message }],
+    },
+  };
+}
+
+/** Parse a limit value, falling back to 50 unless it is a safe positive integer. */
+function parseLimit(value: string | undefined): number {
+  if (!value || !POSITIVE_INT_PATTERN.test(value)) return 50;
+  const num = Number.parseInt(value, 10);
+  return Number.isSafeInteger(num) && num > 0 ? num : 50;
+}
+
+/** Normalize a target path to `/<path>/tag/`, or the Wikidot default. */
+function normalizeTarget(value: string | undefined): string {
+  if (!value) return "/system:page-tags/tag/";
+  let target = value;
+  if (!target.startsWith("/")) target = `/${target}`;
+  if (!target.endsWith("/")) target = `${target}/`;
+  return `${target}tag/`;
+}
+
+/** Parse a `R,G,B` color string into a tuple (input must match COLOR_PATTERN). */
+function parseColor(value: string): [number, number, number] {
+  const [r = 0, g = 0, b = 0] = value.split(",").map((part) => Number.parseInt(part, 10));
+  return [r, g, b];
+}
+
+/**
+ * Module rule for `[[module TagCloud]]`.
+ *
+ * Displays a weighted cloud of page tags. Font sizes and colors are only
+ * honored when both min and max are given (Wikidot behavior); otherwise the
+ * defaults (100%-300%, rgb(128,128,192)-rgb(64,64,128)) apply. Tag data is
+ * supplied during the resolution phase via `DataProvider.fetchTagCloud`.
+ */
+export const tagCloudModuleRule: ModuleRule = {
+  name: "module-tagcloud",
+  acceptsNames: ["tagcloud"],
+  hasBody: false,
+
+  parse(_ctx, _pos, args): Module | Element {
+    const maxFontSize = args.maxfontsize;
+    const minFontSize = args.minfontsize;
+    const maxColor = args.maxcolor;
+    const minColor = args.mincolor;
+
+    let sizeSmall = 100;
+    let sizeBig = 300;
+    let fontSizeUnit: CssLengthUnit = "%";
+    if (maxFontSize && minFontSize) {
+      const maxMatch = FONT_SIZE_PATTERN.exec(maxFontSize);
+      if (!maxMatch) return errorBlock(ERROR_FONT_FORMAT);
+      const maxUnit = (maxMatch[2] as string).toLowerCase() as CssLengthUnit;
+      const minMatch = FONT_SIZE_PATTERN.exec(minFontSize);
+      if (!minMatch || (minMatch[2] as string).toLowerCase() !== maxUnit) {
+        return errorBlock(ERROR_FONT_MISMATCH);
+      }
+      sizeBig = Number.parseInt(maxMatch[1] as string, 10);
+      sizeSmall = Number.parseInt(minMatch[1] as string, 10);
+      fontSizeUnit = maxUnit;
+    }
+
+    let colorSmall: [number, number, number] = [128, 128, 192];
+    let colorBig: [number, number, number] = [64, 64, 128];
+    if (maxColor && minColor) {
+      if (!COLOR_PATTERN.test(maxColor) || !COLOR_PATTERN.test(minColor)) {
+        return errorBlock(ERROR_COLOR_FORMAT);
+      }
+      colorSmall = parseColor(minColor);
+      colorBig = parseColor(maxColor);
+    }
+
+    return {
+      module: "tag-cloud",
+      "min-font-size": sizeSmall,
+      "max-font-size": sizeBig,
+      "font-size-unit": fontSizeUnit,
+      "min-color": colorSmall,
+      "max-color": colorBig,
+      target: normalizeTarget(args.target),
+      limit: parseLimit(args.limit),
+      category: args.category || null,
+    };
+  },
+};

package/src/parser/rules/block/module/tagcloud/resolve.ts

@@ -0,0 +1,173 @@
+/**
+ *
+ * TagCloud module resolution.
+ *
+ * After the application has fetched tag data based on the extracted
+ * requirements, this module expands the `tag-cloud` AST node into concrete
+ * elements: a `div.pages-tag-cloud-box` container with one `a.tag` anchor per
+ * tag, styled with linearly interpolated font sizes and colors, matching
+ * Wikidot's `PagesTagCloudModule` output.
+ *
+ * Unlike ListPages/ListUsers there is no template body, so the expansion
+ * builds AST elements directly instead of re-parsing wikitext.
+ *
+ * Note: TagCloud modules appearing inside the expanded output of other
+ * dynamic modules (e.g. a ListPages body) are not resolved — the resolver
+ * does not re-walk expansion results. This matches the behavior of all
+ * dynamic modules.
+ *
+ * @module
+ */
+
+import type { Element, Module } from "@wdprlib/ast";
+import type { TagCloudExternalData, TagCloudTagData } from "./types";
+
+/**
+ * Narrowed type for the tag-cloud variant of the Module discriminated union.
+ */
+export type TagCloudModuleData = Extract<Module, { module: "tag-cloud" }>;
+
+/**
+ * Type guard to check if a Module is a tag-cloud module.
+ *
+ * @param module - A Module discriminated union value
+ * @returns true if the module is a tag-cloud module
+ */
+export function isTagCloudModule(module: Module): module is TagCloudModuleData {
+  return module.module === "tag-cloud";
+}
+
+/** Wikidot's message shown when the site has no tags at all. */
+const NO_TAGS_MESSAGE_PREFIX =
+  "It seems you have no tags attached to pages. To attach a tag simply click on the ";
+const NO_TAGS_MESSAGE_SUFFIX = " button at the bottom of any page.";
+
+/** Encode a tag for use in a URL path segment, matching PHP's `rawurlencode`. */
+function rawUrlEncode(value: string): string {
+  return encodeURIComponent(value).replace(
+    /[!'()*]/g,
+    (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
+/**
+ * Select and order tags the way Wikidot's SQL does: weight descending
+ * (ties broken by tag name ascending) limited to `limit`, then tag name
+ * ascending for display.
+ */
+function selectTags(tags: TagCloudTagData[], limit: number): TagCloudTagData[] {
+  return tags
+    .toSorted((a, b) => b.weight - a.weight || compareTags(a.tag, b.tag))
+    .slice(0, limit)
+    .toSorted((a, b) => compareTags(a.tag, b.tag));
+}
+
+/** Locale-independent code point comparison for deterministic tag ordering. */
+function compareTags(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Resolve a single TagCloud module by expanding fetched tag data into a
+ * `div.pages-tag-cloud-box` with weighted `a.tag` anchors.
+ *
+ * Font sizes and colors are interpolated linearly between the module's
+ * min/max values based on each tag's weight relative to the weight range of
+ * the selected tags (all tags get the minimum when the range is zero).
+ *
+ * @param module - The tag-cloud module data from the AST
+ * @param data - External tag data fetched by the application
+ * @returns Array of AST elements replacing the module node
+ */
+export function resolveTagCloud(module: TagCloudModuleData, data: TagCloudExternalData): Element[] {
+  if (data.status === "category-not-found") {
+    return [
+      {
+        element: "container",
+        data: {
+          type: "div",
+          attributes: { class: "error-block" },
+          elements: [{ element: "text", data: `Category "${data.category}" can not be found.` }],
+        },
+      },
+    ];
+  }
+
+  const tags = selectTags(data.tags, module.limit);
+  if (tags.length === 0) {
+    return [noTagsMessage()];
+  }
+
+  let minWeight = Number.POSITIVE_INFINITY;
+  let maxWeight = Number.NEGATIVE_INFINITY;
+  for (const tag of tags) {
+    if (tag.weight < minWeight) minWeight = tag.weight;
+    if (tag.weight > maxWeight) maxWeight = tag.weight;
+  }
+  const weightRange = maxWeight - minWeight;
+
+  const categorySuffix = data.category !== null ? `/category/${rawUrlEncode(data.category)}` : "";
+
+  const anchors: Element[] = [];
+  for (const tag of tags) {
+    const a = weightRange === 0 ? 0 : (tag.weight - minWeight) / weightRange;
+    const fontSize = interpolate(module["min-font-size"], module["max-font-size"], a);
+    const [r, g, b] = ([0, 1, 2] as const).map((i) =>
+      interpolate(module["min-color"][i], module["max-color"][i], a),
+    ) as [number, number, number];
+
+    anchors.push({ element: "text", data: "\n" });
+    anchors.push({
+      element: "anchor",
+      data: {
+        target: null,
+        attributes: {
+          class: "tag",
+          href: `${module.target}${rawUrlEncode(tag.tag)}${categorySuffix}`,
+          style: `font-size: ${fontSize}${module["font-size-unit"]}; color: rgb(${r}, ${g}, ${b});`,
+        },
+        elements: [{ element: "text", data: tag.tag }],
+      },
+    });
+  }
+  anchors.push({ element: "text", data: "\n" });
+
+  return [
+    {
+      element: "container",
+      data: {
+        type: "div",
+        attributes: { class: "pages-tag-cloud-box" },
+        elements: anchors,
+      },
+    },
+  ];
+}
+
+/** Linearly interpolate between min and max, rounded like PHP's `round`. */
+function interpolate(min: number, max: number, a: number): number {
+  return Math.round(min + (max - min) * a);
+}
+
+/** Wikidot's "no tags" paragraph, shown when the fetcher returns zero tags. */
+function noTagsMessage(): Element {
+  return {
+    element: "container",
+    data: {
+      type: "paragraph",
+      attributes: {},
+      elements: [
+        { element: "text", data: NO_TAGS_MESSAGE_PREFIX },
+        {
+          element: "container",
+          data: {
+            type: "italics",
+            attributes: {},
+            elements: [{ element: "text", data: "tags" }],
+          },
+        },
+        { element: "text", data: NO_TAGS_MESSAGE_SUFFIX },
+      ],
+    },
+  };
+}

package/src/parser/rules/block/module/tagcloud/types.ts

@@ -0,0 +1,85 @@
+/**
+ *
+ * Type definitions for the TagCloud module.
+ *
+ * The `[[module TagCloud]]` block displays a weighted cloud of page tags.
+ * Tag data (tag names and page counts) is supplied by the application via
+ * `DataProvider.fetchTagCloud` during the resolution phase.
+ *
+ * @module
+ */
+
+/**
+ * Data requirement for a single TagCloud module instance.
+ *
+ * Produced by the extraction phase and consumed by the application to
+ * determine what data to fetch.
+ */
+export interface TagCloudDataRequirement {
+  /** Unique identifier for this module instance (sequential, 0-based) */
+  id: number;
+  /** Category filter from the module attributes, or null for all categories */
+  category: string | null;
+  /** Maximum number of tags to display (already defaulted to 50) */
+  limit: number;
+}
+
+/**
+ * A single tag entry with its weight.
+ */
+export interface TagCloudTagData {
+  /** The tag name */
+  tag: string;
+  /** Number of pages carrying this tag (Wikidot's "weight") */
+  weight: number;
+}
+
+/**
+ * External data provided by the application for a single TagCloud module.
+ *
+ * On success, `category` must be the **normalized** category name (Wikidot's
+ * `toUnixName` form, e.g. `"News Foo"` → `"news-foo"`), or null when no
+ * category filter applies; it is used verbatim in generated tag link URLs.
+ * When the requested category does not exist, return
+ * `{ status: "category-not-found", category }` to produce a Wikidot-compatible
+ * error block instead of tag links.
+ */
+export type TagCloudExternalData =
+  | {
+      status: "ok";
+      /** Tags to display (see {@link TagCloudDataFetcher} for ordering) */
+      tags: TagCloudTagData[];
+      /** Normalized category name used in link URLs, or null for all categories */
+      category: string | null;
+    }
+  | {
+      status: "category-not-found";
+      /** The category name that could not be found, used in the error message */
+      category: string;
+    };
+
+/**
+ * Callback to fetch tag data for a TagCloud module.
+ *
+ * Called during the resolution phase for each TagCloud module in the AST.
+ * Like Wikidot, the fetcher should apply the `category` filter and select at
+ * most `limit` tags ordered by weight descending (ties broken by tag name
+ * ascending) — this can be delegated to the database. The resolver defensively
+ * re-applies this ordering and the limit, then sorts the selected tags by tag
+ * name ascending for display.
+ *
+ * Return null/undefined to skip the module (outputs nothing). Exceptions
+ * thrown by the fetcher propagate out of `resolveModules()`; return
+ * `{ status: "category-not-found" }` (or catch errors yourself) to render an
+ * error instead.
+ *
+ * @security `requirement.category` originates from **untrusted user input**
+ * (the module's wikitext attributes). Never interpolate it into SQL — always
+ * use parameterised queries or prepared statements.
+ *
+ * @param requirement - The data requirement describing what data is needed
+ * @returns Tag data, null/undefined to skip, or a Promise of the same
+ */
+export type TagCloudDataFetcher = (
+  requirement: TagCloudDataRequirement,
+) => TagCloudExternalData | null | undefined | Promise<TagCloudExternalData | null | undefined>;

package/src/parser/rules/block/module/types-common.ts

@@ -14,6 +14,7 @@
 
 import type { ListPagesDataFetcher } from "./listpages/types";
 import type { ListUsersDataFetcher } from "./listusers/types";
+import type { TagCloudDataFetcher } from "./tagcloud/types";
 import type { IfTagsResolver } from "./iftags/types";
 import type { IncludeFetcher } from "./include/resolve/types";
 
@@ -59,6 +60,20 @@ export interface DataProvider {
    */
   fetchInclude?: IncludeFetcher;
 
+  /**
+   * Fetch tag weights for `[[module TagCloud]]` expansion.
+   *
+   * Called once per TagCloud instance with its category filter and limit.
+   * Unlike {@link DataProvider.getPageTags} (which returns the current
+   * page's own tags for `[[iftags]]`), this callback returns site-wide
+   * tag statistics: each tag with the number of pages carrying it.
+   *
+   * @security `requirement.category` originates from **untrusted user
+   * input**. Never interpolate it into SQL — always use parameterised
+   * queries or prepared statements.
+   */
+  fetchTagCloud?: TagCloudDataFetcher;
+
   /**
    * Return the current page's tags for `[[iftags]]` evaluation.
    *