@discourse/types 2026.1.0-c7e9cdd → 2026.3.0-d02b2966

package/declarations/app/lib/blocks/-internals/error.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Parses a condition path string into path segments.
+ * Handles both dot notation (`.key`) and bracket notation (`[0]`).
+ *
+ * @param {string} path - The path string (e.g., "conditions.any[0][1].queryParams").
+ * @returns {Array<string|number>} Array of path segments.
+ *
+ * @example
+ * parseConditionPath("conditions.any[0][1].type")
+ * // Returns: ["conditions", "any", 0, 1, "type"]
+ */
+export function parseConditionPath(path: string): Array<string | number>;
+/**
+ * Renders a block entry object with the error path highlighted.
+ * Shows the structure with proper indentation and adds a comment marker
+ * to indicate where the error occurred.
+ *
+ * @param {Object|Array} entry - The block entry object to render.
+ * @param {string} errorPath - The path to the error (e.g., "conditions.any[0][0].queryParams").
+ * @param {Object} [options] - Formatting options.
+ * @param {string} [options.prefix] - Optional prefix to skip in the path (e.g., "conditions").
+ * @param {string} [options.label] - Label to show before the entry (e.g., "conditions:").
+ * @returns {string} Formatted string with the error location highlighted.
+ */
+export function formatEntryWithErrorPath(entry: any | any[], errorPath: string, options?: {
+    prefix?: string;
+    label?: string;
+}): string;
+/**
+ * Truncates an object for JSON serialization in error messages.
+ * Returns actual objects/arrays with truncated content, not strings.
+ *
+ * Note: This returns OBJECTS for JSON.stringify(). For string representations
+ * in console output, use formatTruncatedValue() instead.
+ *
+ * Handles special cases like block classes, children arrays, and circular references.
+ *
+ * @param {*} obj - The object to truncate.
+ * @param {number} [maxDepth=2] - Maximum nesting depth before truncating.
+ * @param {number} [maxKeys=5] - Maximum number of keys to show per object.
+ * @param {WeakSet} [_seen=null] - Internal parameter for tracking circular references.
+ * @returns {*} Truncated representation of the object.
+ */
+export function truncateForDisplay(obj: any, maxDepth?: number, maxKeys?: number, _seen?: WeakSet<any>): any;
+/**
+ * Captures the current call site as an Error object, excluding internal frames.
+ * Call this at the entry point (e.g., renderBlocks) to capture where
+ * the user's code called into the block system.
+ *
+ * Uses `Error.captureStackTrace` (V8-specific) to exclude the calling function
+ * and everything above it from the stack trace. This means the stack will
+ * point directly to the user's code, not to internal block system functions.
+ *
+ * @param {Function} callerFn - The function to exclude from the stack trace.
+ *   Pass the function that calls `captureCallSite` (e.g., `_renderBlocks`).
+ * @returns {Error} An Error object with stack trace starting from callerFn's caller.
+ */
+export function captureCallSite(callerFn: Function): Error;
+/**
+ * Raises a block error by throwing a `BlockError`.
+ *
+ * If context is provided, the error message will include the block
+ * entry for debugging.
+ *
+ * If a `callSiteError` is present in the context, it is reused with the
+ * new message. This preserves the original stack trace pointing to where
+ * `renderBlocks()` was called, which is more useful than pointing to this
+ * function. Source maps are applied automatically by the browser.
+ *
+ * @param {string} message - The error message.
+ * @param {Object} [context] - Optional error context for better error messages.
+ * @param {string} [context.outletName] - The outlet name where the block is registered.
+ * @param {string} [context.blockName] - The name of the block being validated.
+ * @param {string} [context.path] - Path within the layout to the error (e.g., "[2].conditions.params.categoryId").
+ *   Used by validation code to indicate where errors occurred. Combined with `errorPath` for display.
+ * @param {Object} [context.entry] - The block entry being validated.
+ * @param {Object} [context.conditions] - The conditions being validated.
+ * @param {string} [context.errorPath] - Full path to the error for display (e.g., "[2].conditions.params.categoryId").
+ * @param {Array<Object>} [context.rootLayout] - The root outlet layout for tree display in errors.
+ * @param {Error | null} [context.callSiteError] - Error object capturing where renderBlocks() was called.
+ * @throws {BlockError} Always throws.
+ */
+export function raiseBlockError(message: string, context?: {
+    outletName?: string;
+    blockName?: string;
+    path?: string;
+    entry?: any;
+    conditions?: any;
+    errorPath?: string;
+    rootLayout?: Array<any>;
+    callSiteError?: Error | null;
+}): void;
+/**
+ * Error thrown when block validation fails.
+ * Used by block entry and condition validation to report
+ * errors at registration time.
+ *
+ * Supports the standard `cause` option from ES2022 to chain errors together.
+ * Note: `raiseBlockError()` uses a different approach - it reuses the
+ * `callSiteError` directly (mutating its message and name) rather than
+ * passing it as `cause`. This preserves the original stack trace pointing
+ * to where `renderBlocks()` was called.
+ *
+ * @class BlockError
+ * @extends Error
+ */
+export class BlockError extends Error {
+    /**
+     * Creates a new BlockError.
+     *
+     * @param {string} message - The error message.
+     * @param {Object} [options] - Error options.
+     * @param {Error} [options.cause] - The underlying cause of this error.
+     * @param {string} [options.path] - Path to the error within the layout
+     *   (e.g., "[0].conditions.any[0].type" or "[0].args.showIcon").
+     */
+    constructor(message: string, options?: {
+        cause?: Error;
+        path?: string;
+    });
+    path: string;
+}
+//# sourceMappingURL=error.d.ts.map

package/declarations/app/lib/blocks/-internals/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../../../../discourse/app/lib/blocks/-internals/error.js"],"names":[],"mappings":"AAoEA;;;;;;;;;;GAUG;AACH,yCAPW,MAAM,GACJ,KAAK,CAAC,MAAM,GAAC,MAAM,CAAC,CAyChC;AAiWD;;;;;;;;;;;GAWG;AACH,gDAPW,WAAY,aACZ,MAAM,YAEd;IAAyB,MAAM,GAAvB,MAAM;IACW,KAAK,GAAtB,MAAM;CACd,GAAU,MAAM,CAIlB;AAED;;;;;;;;;;;;;;GAcG;AACH,wCANW,GAAC,aACD,MAAM,YACN,MAAM,yBAEJ,GAAC,CA0Db;AAID;;;;;;;;;;;;GAYG;AACH,qDAFa,KAAK,CAcjB;AAwMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,yCAbW,MAAM,YAEd;IAAyB,UAAU,GAA3B,MAAM;IACW,SAAS,GAA1B,MAAM;IACW,IAAI,GAArB,MAAM;IAEW,KAAK;IACL,UAAU;IACV,SAAS,GAA1B,MAAM;IACkB,UAAU,GAAlC,KAAK,KAAQ;IACU,aAAa,GAApC,KAAK,GAAG,IAAI;CACpB,QAuCF;AA5FD;;;;;;;;;;;;;GAaG;AACH;IACE;;;;;;;;OAQG;IACH,qBANW,MAAM,YAEd;QAAwB,KAAK,GAArB,KAAK;QACY,IAAI,GAArB,MAAM;KAEhB,EAKA;IADC,aAAyB;CAE5B"}

package/declarations/app/lib/blocks/-internals/matching/condition-evaluator.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Evaluates condition specs at render time.
+ * Recursively evaluates nested conditions with AND/OR/NOT logic.
+ *
+ * @param {Object|Array<Object>} conditionSpec - Condition spec(s) to evaluate.
+ * @param {Map<string, import("discourse/blocks/conditions").BlockCondition>} conditionTypes - Map of registered condition types.
+ * @param {Object} [context] - Evaluation context.
+ * @param {boolean} [context.debug] - Enable debug logging for this evaluation.
+ * @param {number} [context._depth] - Internal: nesting depth for logging.
+ * @param {Object} [context.outletArgs] - Outlet arguments passed to conditions.
+ * @returns {boolean} True if conditions pass, false otherwise.
+ */
+export function evaluateConditions(conditionSpec: any | Array<any>, conditionTypes: Map<string, import("discourse/blocks/conditions").BlockCondition>, context?: {
+    debug?: boolean;
+    _depth?: number;
+    outletArgs?: any;
+}): boolean;
+//# sourceMappingURL=condition-evaluator.d.ts.map

package/declarations/app/lib/blocks/-internals/matching/condition-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"condition-evaluator.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/matching/condition-evaluator.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;GAWG;AACH,kDARW,MAAO,KAAK,KAAQ,kBACpB,GAAG,CAAC,MAAM,EAAE,OAAO,6BAA6B,EAAE,cAAc,CAAC,YAEzE;IAA0B,KAAK,GAAvB,OAAO;IACU,MAAM,GAAvB,MAAM;IACW,UAAU;CACnC,GAAU,OAAO,CA6EnB"}

package/declarations/app/lib/blocks/-internals/matching/outlet-matcher.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Checks if a pattern targets a namespaced outlet.
+ *
+ * Namespaced outlets use a colon separator to identify outlets defined by
+ * plugins or themes (e.g., `plugin-name:outlet-name`, `theme-name:outlet-name`).
+ * These patterns bypass known-outlet validation since they reference outlets
+ * that may not be in the core `BLOCK_OUTLETS` registry.
+ *
+ * @param {string} pattern - The pattern to check.
+ * @returns {boolean} True if the pattern contains a namespace separator.
+ *
+ * @example
+ * isNamespacedPattern("my-plugin:dashboard");      // true
+ * isNamespacedPattern("my-theme:hero-section");    // true
+ * isNamespacedPattern("sidebar-blocks");           // false
+ * isNamespacedPattern("sidebar-*");                // false
+ */
+export function isNamespacedPattern(pattern: string): boolean;
+/**
+ * Matches an outlet name against a glob pattern using picomatch.
+ *
+ * Outlet names follow kebab-case (lowercase letters, numbers, hyphens).
+ * Supported glob syntax:
+ * - `*` matches any characters
+ * - `?` matches a single character
+ * - `[abc]` matches any character in the brackets
+ * - `{a,b}` matches any of the comma-separated patterns
+ * - `!(pattern)` negative match (matches anything except pattern)
+ *
+ * @param {string} outlet - The outlet name to test.
+ * @param {string} pattern - The glob pattern to match against.
+ * @returns {boolean} True if the outlet matches the pattern.
+ *
+ * @example
+ * // Exact match
+ * matchOutletPattern("sidebar-blocks", "sidebar-blocks");   // true
+ *
+ * @example
+ * // Wildcard matching
+ * matchOutletPattern("sidebar-left", "sidebar-*");          // true
+ * matchOutletPattern("sidebar-left-top", "sidebar-*");      // true
+ *
+ * @example
+ * // Brace expansion
+ * matchOutletPattern("sidebar-blocks", "{sidebar,footer}-*"); // true
+ *
+ * @example
+ * // Character class
+ * matchOutletPattern("modal-1", "modal-[0-9]");             // true
+ *
+ * @example
+ * // Negation
+ * matchOutletPattern("sidebar-blocks", "!(*-debug)");       // true
+ */
+export function matchOutletPattern(outlet: string, pattern: string): boolean;
+/**
+ * Validates that outlet patterns are a valid array of strings with valid picomatch syntax.
+ *
+ * This function is called at decoration time to catch configuration errors early.
+ * It validates:
+ * 1. The patterns parameter is an array (or null/undefined for no restrictions)
+ * 2. Each pattern in the array is a string
+ * 3. Each pattern can be compiled by picomatch
+ *
+ * @param {*} patterns - The patterns to validate.
+ * @param {string} blockName - Block name for error messages.
+ * @param {string} propertyName - Property name ("allowedOutlets" or "deniedOutlets").
+ *
+ * @example
+ * validateOutletPatterns(["sidebar-*", "homepage-blocks"], "my-block", "allowedOutlets");
+ * validateOutletPatterns(null, "my-block", "allowedOutlets"); // null means no restrictions
+ */
+export function validateOutletPatterns(patterns: any, blockName: string, propertyName: string): void;
+/**
+ * Detects if allowed and denied patterns could match the same outlet name.
+ *
+ * This function uses two strategies to detect conflicts:
+ *
+ * 1. **Known outlets check**: Tests each registered outlet (core and custom)
+ *    against both pattern lists. This catches conflicts for outlets that
+ *    actually exist.
+ *
+ * 2. **Synthetic test strings**: Generates test strings by replacing wildcards
+ *    in patterns with concrete characters. This catches conflicts for outlets
+ *    that don't exist yet (e.g., plugin-defined outlets).
+ *
+ * @param {string[]|null} allowedPatterns - Patterns for allowed outlets.
+ * @param {string[]|null} deniedPatterns - Patterns for denied outlets.
+ * @returns {{ conflict: boolean, details?: { outlet: string, allowed: string, denied: string } }}
+ *   Returns conflict: true with details if a conflict is detected.
+ *
+ * @example
+ * // No conflict
+ * detectPatternConflicts(["sidebar-*"], ["homepage-*"]);
+ * // { conflict: false }
+ *
+ * @example
+ * // Conflict detected
+ * detectPatternConflicts(["*-blocks"], ["sidebar-*"]);
+ * // { conflict: true, details: { outlet: "sidebar-blocks", allowed: "*-blocks", denied: "sidebar-*" } }
+ */
+export function detectPatternConflicts(allowedPatterns: string[] | null, deniedPatterns: string[] | null): {
+    conflict: boolean;
+    details?: {
+        outlet: string;
+        allowed: string;
+        denied: string;
+    };
+};
+/**
+ * Checks if a block is permitted to render in a specific outlet.
+ *
+ * The permission check follows these rules:
+ * 1. If `deniedPatterns` is specified and the outlet matches any pattern, deny.
+ * 2. If `allowedPatterns` is specified and the outlet doesn't match any pattern, deny.
+ * 3. Otherwise, permit.
+ *
+ * Denial takes precedence over allowance. An empty `allowedOutlets` array means
+ * "no outlets allowed" (strict whitelist).
+ *
+ * @param {string} outlet - The outlet name to check.
+ * @param {string[]|null} allowedPatterns - Patterns for allowed outlets.
+ * @param {string[]|null} deniedPatterns - Patterns for denied outlets.
+ * @returns {{ permitted: boolean, reason?: string }}
+ *   Returns permitted: true if allowed, or permitted: false with a reason if denied.
+ *
+ * @example
+ * // No restrictions
+ * isBlockPermittedInOutlet("sidebar-blocks", null, null);
+ * // { permitted: true }
+ *
+ * @example
+ * // Allowed by pattern
+ * isBlockPermittedInOutlet("sidebar-blocks", ["sidebar-*"], null);
+ * // { permitted: true }
+ *
+ * @example
+ * // Denied by pattern
+ * isBlockPermittedInOutlet("sidebar-blocks", null, ["sidebar-*"]);
+ * // { permitted: false, reason: 'outlet "sidebar-blocks" matches deniedOutlets pattern "sidebar-*"' }
+ *
+ * @example
+ * // Not in allowed list
+ * isBlockPermittedInOutlet("homepage-blocks", ["sidebar-*"], null);
+ * // { permitted: false, reason: 'outlet "homepage-blocks" does not match any allowedOutlets pattern' }
+ */
+export function isBlockPermittedInOutlet(outlet: string, allowedPatterns: string[] | null, deniedPatterns: string[] | null): {
+    permitted: boolean;
+    reason?: string;
+};
+/**
+ * Warns if patterns don't match any known outlet (helps catch typos).
+ *
+ * This function is called at decoration time to help developers catch
+ * configuration mistakes. It checks patterns against all registered outlets
+ * (both core and custom).
+ *
+ * Warnings are only printed in development builds (when DEBUG is true).
+ * This prevents noise in production.
+ *
+ * @param {string[]|null} patterns - The patterns to check.
+ * @param {string} blockName - Block name for warning messages.
+ * @param {string} propertyName - Property name ("allowedOutlets" or "deniedOutlets").
+ *
+ * @example
+ * // Warns about typo
+ * warnUnknownOutletPatterns(["sidbar-*"], "my-block", "allowedOutlets");
+ * // Console: [Blocks] Block "my-block": allowedOutlets pattern "sidbar-*" does not match any known outlet...
+ */
+export function warnUnknownOutletPatterns(patterns: string[] | null, blockName: string, propertyName: string): void;
+//# sourceMappingURL=outlet-matcher.d.ts.map

package/declarations/app/lib/blocks/-internals/matching/outlet-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outlet-matcher.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/matching/outlet-matcher.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;GAgBG;AACH,6CATW,MAAM,GACJ,OAAO,CAUnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,2CAzBW,MAAM,WACN,MAAM,GACJ,OAAO,CA2BnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,iDARW,GAAC,aACD,MAAM,gBACN,MAAM,QAuChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wDAfW,MAAM,EAAE,GAAC,IAAI,kBACb,MAAM,EAAE,GAAC,IAAI,GACX;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAuEhG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,iDA1BW,MAAM,mBACN,MAAM,EAAE,GAAC,IAAI,kBACb,MAAM,EAAE,GAAC,IAAI,GACX;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAmEnD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,oDATW,MAAM,EAAE,GAAC,IAAI,aACb,MAAM,gBACN,MAAM,QAkChB"}

package/declarations/app/lib/blocks/-internals/matching/page-definitions.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Checks if a page type is valid.
+ *
+ * @param {string} pageType - The page type to check.
+ * @returns {boolean} True if the page type is valid.
+ */
+export function isValidPageType(pageType: string): boolean;
+/**
+ * Gets the parameter definitions for a page type.
+ *
+ * @param {string} pageType - The page type.
+ * @returns {Object<string, ParamDefinition>|null} The parameter definitions, or null if invalid.
+ */
+export function getParamsForPageType(pageType: string): {
+    [x: string]: ParamDefinition;
+} | null;
+/**
+ * Gets all valid parameter names for a page type.
+ *
+ * @param {string} pageType - The page type.
+ * @returns {string[]} Array of valid parameter names.
+ */
+export function getValidParamNames(pageType: string): string[];
+/**
+ * Suggests a page type for a potential typo using fuzzy matching.
+ *
+ * @param {string} typo - The potentially misspelled page type.
+ * @returns {string|null} The suggested page type, or null if no good match found.
+ */
+export function suggestPageType(typo: string): string | null;
+/**
+ * Validates that all provided params are valid for ALL listed page types.
+ *
+ * @param {Object} params - The params object to validate.
+ * @param {string[]} pages - The array of page types.
+ * @returns {{valid: boolean, errors: string[]}} Validation result with any errors.
+ */
+export function validateParamsAgainstPages(params: any, pages: string[]): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Validates the type of a parameter value against its definition.
+ *
+ * @param {string} paramName - The parameter name.
+ * @param {*} value - The value to validate.
+ * @param {string} pageType - The page type (for error messages).
+ * @returns {{valid: boolean, error: string|null}} Validation result.
+ */
+export function validateParamType(paramName: string, value: any, pageType: string): {
+    valid: boolean;
+    error: string | null;
+};
+/**
+ * Gets the current context values for a page type.
+ *
+ * Returns an object with the current values for all parameters defined for
+ * this page type, or null if the page type doesn't match the current route.
+ *
+ * @param {string} pageType - The page type (e.g., "CATEGORY_PAGES").
+ * @param {Object} services - Injected services for context extraction.
+ * @param {Object} services.router - The Ember router service.
+ * @param {Object} services.discovery - The Discourse discovery service.
+ * @returns {Object|null} The context object with param values, or null if page type doesn't match.
+ *
+ * @example
+ * const context = getPageContext("CATEGORY_PAGES", { router, discovery });
+ * // Returns { categoryId: 5, categorySlug: "general", parentCategoryId: null }
+ * // or null if not on a category page
+ */
+export function getPageContext(pageType: string, { router, discovery }: {
+    router: any;
+    discovery: any;
+}): any | null;
+/**
+ * Determines the current page type by checking all known page types.
+ *
+ * Iterates through all valid page types and returns the first one that matches
+ * the current route. Useful for debugging to show what page the user is on.
+ *
+ * @param {Object} services - Injected services for context extraction.
+ * @param {Object} services.router - The Ember router service.
+ * @param {Object} services.discovery - The Discourse discovery service.
+ * @returns {string|null} The current page type, or null if no match.
+ *
+ * @example
+ * const pageType = getCurrentPageType({ router, discovery });
+ * // Returns "CATEGORY_PAGES", "TOPIC_PAGES", etc., or null
+ */
+export function getCurrentPageType({ router, discovery }: {
+    router: any;
+    discovery: any;
+}): string | null;
+/**
+ * Page type definitions for the route condition.
+ *
+ * This is a pure data structure that defines the available page types
+ * and their parameters. The evaluation logic is in route.js.
+ *
+ * @typedef {Object} ParamDefinition
+ * @property {"string"|"number"} type - The expected type of the parameter.
+ * @property {string} description - A description of the parameter.
+ *
+ * @typedef {Object} PageDefinition
+ * @property {string} description - A description of the page type.
+ * @property {Object<string, ParamDefinition>} params - The parameters for this page type.
+ */
+/**
+ * Definitions for all supported page types.
+ *
+ * Each page type has:
+ * - `description`: A human-readable description of what pages this matches.
+ * - `params`: An object mapping parameter names to their definitions.
+ *
+ * @type {Object<string, PageDefinition>}
+ */
+export const PAGE_DEFINITIONS: {
+    [x: string]: PageDefinition;
+};
+/**
+ * Array of all valid page type names.
+ *
+ * @type {string[]}
+ */
+export const VALID_PAGE_TYPES: string[];
+/**
+ * Page type definitions for the route condition.
+ *
+ * This is a pure data structure that defines the available page types
+ * and their parameters. The evaluation logic is in route.js.
+ */
+export type ParamDefinition = {
+    /**
+     * - The expected type of the parameter.
+     */
+    type: "string" | "number";
+    /**
+     * - A description of the parameter.
+     */
+    description: string;
+};
+/**
+ * Page type definitions for the route condition.
+ *
+ * This is a pure data structure that defines the available page types
+ * and their parameters. The evaluation logic is in route.js.
+ */
+export type PageDefinition = {
+    /**
+     * - A description of the page type.
+     */
+    description: string;
+    /**
+     * - The parameters for this page type.
+     */
+    params: {
+        [x: string]: ParamDefinition;
+    };
+};
+//# sourceMappingURL=page-definitions.d.ts.map

package/declarations/app/lib/blocks/-internals/matching/page-definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-definitions.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/matching/page-definitions.js"],"names":[],"mappings":"AA6KA;;;;;GAKG;AACH,0CAHW,MAAM,GACJ,OAAO,CAInB;AAED;;;;;GAKG;AACH,+CAHW,MAAM,GACJ;QAAO,MAAM,GAAE,eAAe;CAAC,GAAC,IAAI,CAKhD;AAED;;;;;GAKG;AACH,6CAHW,MAAM,GACJ,MAAM,EAAE,CAKpB;AAED;;;;;GAKG;AACH,sCAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAIvB;AAED;;;;;;GAMG;AACH,+DAHW,MAAM,EAAE,GACN;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAC,CAkD9C;AAED;;;;;;;GAOG;AACH,6CALW,MAAM,SACN,GAAC,YACD,MAAM,GACJ;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,GAAC,IAAI,CAAA;CAAC,CA8BhD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,yCAXW,MAAM,yBAEd;IAAyB,MAAM;IACN,SAAS;CAClC,GAAU,MAAO,IAAI,CAgGvB;AAED;;;;;;;;;;;;;;GAcG;AACH,0DARG;IAAyB,MAAM;IACN,SAAS;CAClC,GAAU,MAAM,GAAC,IAAI,CAavB;AArbD;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;GAQG;AACH;;EAyIE;AAEF;;;;GAIG;AACH,+BAFU,MAAM,EAAE,CAE4C;;;;;;;;;;;UAjKhD,QAAQ,GAAC,QAAQ;;;;iBACjB,MAAM;;;;;;;;;;;;iBAGN,MAAM"}

package/declarations/app/lib/blocks/-internals/matching/url-matcher.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Normalizes a URL path for matching.
+ *
+ * This function prepares a URL for glob pattern matching by:
+ * 1. Stripping the Discourse subfolder prefix (if Discourse runs on `/forum`, etc.)
+ * 2. Removing query strings and hash fragments
+ * 3. Removing trailing slashes (except for root `/`)
+ *
+ * This ensures theme authors don't need to know about subfolder configurations
+ * and can write patterns like `/c/**` that work universally.
+ *
+ * @param {string} url - The URL to normalize (typically `router.currentURL`).
+ * @returns {string} The normalized path, ready for pattern matching.
+ *
+ * @example
+ * // Subfolder stripping
+ * normalizePath("/forum/c/general");     // "/c/general"
+ *
+ * // Query string removal
+ * normalizePath("/c/general?foo=bar");   // "/c/general"
+ *
+ * // Hash fragment removal
+ * normalizePath("/c/general#section");   // "/c/general"
+ *
+ * // Trailing slash removal
+ * normalizePath("/c/general/");          // "/c/general"
+ *
+ * // Root path preserved
+ * normalizePath("/");                    // "/"
+ *
+ * // Empty/null handling
+ * normalizePath("");                     // "/"
+ * normalizePath(null);                   // "/"
+ */
+export function normalizePath(url: string): string;
+/**
+ * Matches a URL path against a glob pattern using picomatch.
+ *
+ * Supports full picomatch glob syntax:
+ * - `*` matches a single path segment (no slashes)
+ * - `**` matches zero or more path segments
+ * - `?` matches a single character
+ * - `[abc]` matches any character in the brackets
+ * - `{a,b}` matches any of the comma-separated patterns
+ *
+ * @param {string} path - The normalized URL path to test.
+ * @param {string} pattern - The glob pattern to match against.
+ * @returns {boolean} True if the path matches the pattern.
+ *
+ * @example
+ * // Single wildcard
+ * matchUrlPattern("/c/general", "/c/*");      // true
+ * matchUrlPattern("/c/general/sub", "/c/*");  // false
+ *
+ * @example
+ * // Double wildcard
+ * matchUrlPattern("/c/general/sub", "/c/**"); // true
+ *
+ * @example
+ * // Brace expansion
+ * matchUrlPattern("/latest", "/{latest,top}"); // true
+ */
+export function matchUrlPattern(path: string, pattern: string): boolean;
+/**
+ * Checks if any URL pattern in the array matches the given path.
+ *
+ * @param {string} path - The normalized URL path to test.
+ * @param {string[]} patterns - Array of URL patterns.
+ * @returns {boolean} True if any pattern matches the path.
+ *
+ * @example
+ * matchesAnyPattern("/c/general", ["/c/**", "/t/**"]); // true (matches /c/**)
+ * matchesAnyPattern("/latest", ["/c/**", "/t/**"]);    // false
+ */
+export function matchesAnyPattern(path: string, patterns: string[]): boolean;
+//# sourceMappingURL=url-matcher.d.ts.map

package/declarations/app/lib/blocks/-internals/matching/url-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-matcher.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/matching/url-matcher.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,mCAvBW,MAAM,GACJ,MAAM,CAuClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,sCAjBW,MAAM,WACN,MAAM,GACJ,OAAO,CAkBnB;AAED;;;;;;;;;;GAUG;AACH,wCARW,MAAM,YACN,MAAM,EAAE,GACN,OAAO,CAQnB"}

package/declarations/app/lib/blocks/-internals/matching/value-matcher.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Evaluates a value matcher spec against an actual value.
+ * Supports the same AND/OR/NOT logic as condition evaluation.
+ *
+ * Supports:
+ * - Exact match: `123`, `"foo"`
+ * - Array of simple values (OR): `[123, 456]` matches if actual is any of these
+ * - Array of complex specs (AND): `[{ not: "a" }, { not: "b" }]` all specs must match
+ * - RegExp: `/^foo/` matches if actual matches the pattern
+ * - NOT: `{ not: value }` matches if actual does NOT match value
+ * - ANY (OR): `{ any: [...] }` matches if actual matches any spec in array
+ *
+ * @param {Object} options - Options object.
+ * @param {*} options.actual - The actual value to test.
+ * @param {*} options.expected - The expected value spec (exact, array, regex, or AND/OR/NOT spec).
+ * @returns {boolean} True if the actual value matches the expected spec.
+ */
+export function matchValue({ actual, expected }: {
+    actual: any;
+    expected: any;
+}): boolean;
+/**
+ * Checks if a failed match is due to a string/number type mismatch.
+ * Used to provide helpful debug hints.
+ *
+ * @param {*} actual - The actual value.
+ * @param {*} expected - The expected value.
+ * @returns {boolean} True if the values would match with type coercion.
+ */
+export function isTypeMismatch(actual: any, expected: any): boolean;
+/**
+ * Evaluates params/queryParams object matching with full AND/OR/NOT support.
+ *
+ * Supports:
+ * - Object with keys: AND logic (all keys must match)
+ * - Array of objects: AND logic (all must match)
+ * - `{ any: [...] }`: OR logic (any must match)
+ * - `{ not: {...} }`: NOT logic (must NOT match)
+ *
+ * Keys starting with backslash are escaped (e.g., `"\\any"` matches literal param `"any"`).
+ *
+ * @param {Object} options - Options object.
+ * @param {Object} options.actualParams - Current params from router.
+ * @param {Object|Array} options.expectedParams - Expected params spec.
+ * @param {Object} [options.context] - Debug context.
+ * @param {boolean} [options.context.debug] - Enable debug logging.
+ * @param {number} [options.context._depth] - Nesting depth for logging.
+ * @param {Object} [options.context.logger] - Logger interface from dev-tools (optional).
+ * @param {string} [options.label] - Label for debug output (e.g., "params", "queryParams").
+ * @returns {boolean} True if params match.
+ */
+export function matchParams({ actualParams, expectedParams, context, label, }: {
+    actualParams: any;
+    expectedParams: any | any[];
+    context?: {
+        debug?: boolean;
+        _depth?: number;
+        logger?: any;
+    };
+    label?: string;
+}): boolean;
+/**
+ * Validates a param spec for typos in operator keys.
+ *
+ * Recursively checks that any object key that looks like an operator typo
+ * (e.g., "an" instead of "any", "nto" instead of "not") is flagged.
+ *
+ * @param {*} spec - The param spec to validate.
+ * @param {string} path - Current path for error messages.
+ * @param {Function} raiseError - Function to call with error message.
+ */
+export function validateParamSpec(spec: any, path: string, raiseError: Function): void;
+//# sourceMappingURL=value-matcher.d.ts.map

package/declarations/app/lib/blocks/-internals/matching/value-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-matcher.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/matching/value-matcher.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,iDAJG;IAAmB,MAAM,EAAjB,GAAC;IACU,QAAQ,EAAnB,GAAC;CACT,GAAU,OAAO,CA0BnB;AA2CD;;;;;;;GAOG;AACH,uCAJW,GAAC,YACD,GAAC,GACC,OAAO,CA2BnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,+EATG;IAAwB,YAAY;IACN,cAAc,EAApC,WAAY;IACK,OAAO,GAChC;QAAkC,KAAK,GAA/B,OAAO;QACkB,MAAM,GAA/B,MAAM;QACmB,MAAM;KACvC;IAAyB,KAAK,GAAtB,MAAM;CACd,GAAU,OAAO,CA4HnB;AAQD;;;;;;;;;GASG;AACH,wCAJW,GAAC,QACD,MAAM,8BA0ChB"}