@discourse/types 2026.8.0-fb9247e0 → 2026.9.0-c0ef3a11

package/declarations/app/blocks/builtin/block-group.d.ts

@@ -1,6 +1,13 @@
+import Component from "@glimmer/component";
+import type { ChildBlockResult } from "discourse/lib/blocks/-internals/types";
+interface GroupedBlocksSignature {
+    Args: {
+        children: ChildBlockResult[];
+    };
+}
 /**
  * A container block that groups multiple children blocks together.
- * Rendered children are pre-processed by the block outlet system and passed via the @children arg.
+ * Rendered children are pre-processed by the block outlet system and passed via the `@children` arg.
  *
  * The system wrapper provides standard BEM classes:
  * - `{outletName}__block-container` - Standard container class
@@ -10,8 +17,7 @@
  * - `@outletName` - The outlet identifier this group belongs to
  * - `@outletArgs` - Outlet args available for condition evaluation and access
  */
-export default class GroupedBlocks extends Component<any> {
-    constructor(owner: import("@ember/-internals/owner").default, args: any);
+export default class GroupedBlocks extends Component<GroupedBlocksSignature> {
 }
-import Component from "@glimmer/component";
+export {};
 //# sourceMappingURL=block-group.d.ts.map

package/declarations/app/blocks/builtin/block-group.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"block-group.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/builtin/block-group.gjs"],"names":[],"mappings":"AA+BA;;;;;;;;;;;GAWG;AACH;;CAkBC;sBAjCqB,oBAAoB"}
+{"version":3,"file":"block-group.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/builtin/block-group.gts"],"names":[],"mappings":"AAAA,OAiCO,SAAS,MAAM,oBAAoB,CAAC;AAE3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAE9E,UAAU,sBAAsB;IAC9B,IAAI,EAAE;QACJ,QAAQ,EAAE,gBAAgB,EAAE,CAAC;KAC9B,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AAKH,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,SAAS,CAAC,sBAAsB,CAAC;CAc3E"}

package/declarations/app/blocks/builtin/block-head.d.ts

@@ -1,3 +1,11 @@
+import Component from "@glimmer/component";
+import type { ChildBlockResult } from "discourse/lib/blocks/-internals/types";
+import type Blocks from "discourse/services/blocks";
+interface HeadBlockSignature {
+    Args: {
+        children: ChildBlockResult[];
+    };
+}
 /**
  * A container block that renders only its first visible child.
  *
@@ -16,7 +24,7 @@
  * not display children 2+, we are responsible for:
  *
  * 1. Rendering ghosts for children that failed their own conditions
- *    (already ghost blocks in @children)
+ *    (already ghost blocks in `@children`)
  * 2. Converting children that passed conditions but aren't rendered
  *    (because another sibling was first) into ghosts with an explanation
  *
@@ -47,21 +55,21 @@
  * ]);
  * ```
  */
-export default class HeadBlock extends Component<any> {
-    constructor(owner: import("@ember/-internals/owner").default, args: any);
-    blocks: any;
+export default class HeadBlock extends Component<HeadBlockSignature> {
+    blocks: Blocks;
     /**
      * Children that passed their conditions and could be rendered.
-     *
-     * @returns {Array<import("discourse/lib/blocks/-internals/entry-processing").ChildBlockResult>}
      */
-    get renderableChildren(): Array<import("discourse/lib/blocks/-internals/entry-processing").ChildBlockResult>;
+    get renderableChildren(): ChildBlockResult[];
     /**
      * The one child we actually render (first that passed conditions).
-     *
-     * @returns {import("discourse/lib/blocks/-internals/entry-processing").ChildBlockResult|undefined}
      */
-    get firstChild(): import("discourse/lib/blocks/-internals/entry-processing").ChildBlockResult | undefined;
+    get firstChild(): ChildBlockResult | undefined;
+    /**
+     * Converts a passed-over sibling into a ghost with the given reason,
+     * for the debug visual overlay.
+     */
+    ghostify(child: ChildBlockResult, reason: string): ChildBlockResult | null;
 }
-import Component from "@glimmer/component";
+export {};
 //# sourceMappingURL=block-head.d.ts.map

package/declarations/app/blocks/builtin/block-head.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"block-head.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/builtin/block-head.gjs"],"names":[],"mappings":"AA6HA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;;IAKE,YAAgB;IAEhB;;;;OAIG;IACH,0BAFa,KAAK,CAAC,OAAO,kDAAkD,EAAE,gBAAgB,CAAC,CAI9F;IAED;;;;OAIG;IACH,kBAFa,OAAO,kDAAkD,EAAE,gBAAgB,GAAC,SAAS,CAIjG;CA4CF;sBA1HqB,oBAAoB"}
+{"version":3,"file":"block-head.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/builtin/block-head.gts"],"names":[],"mappings":"AAAA,OAiIO,SAAS,MAAM,oBAAoB,CAAC;AAG3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,KAAK,MAAM,MAAM,2BAA2B,CAAC;AAIpD,UAAU,kBAAkB;IAC1B,IAAI,EAAE;QACJ,QAAQ,EAAE,gBAAgB,EAAE,CAAC;KAC9B,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAKH,MAAM,CAAC,OAAO,OAAO,SAAU,SAAQ,SAAS,CAAC,kBAAkB,CAAC;IACjD,MAAM,EAAE,MAAM,CAAC;IAEhC;;OAEG;IACH,IAAI,kBAAkB,IAAI,gBAAgB,EAAE,CAE3C;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,gBAAgB,GAAG,SAAS,CAE7C;IAED;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;CA8C3E"}

package/declarations/app/blocks/builtin/index.d.ts

@@ -1,3 +1,33 @@
+/**
+ * Built-in blocks registry.
+ *
+ * This module lists all built-in block components provided by Discourse.
+ * These blocks are registered at runtime by the `freeze-block-registry`
+ * initializer, which imports from this file and calls `api.registerBlock()`
+ * for each exported block.
+ *
+ * ## Adding a New Built-in Block
+ *
+ * 1. Create the block component in `app/blocks/builtin/` with the `@block` decorator:
+ *
+ * ```javascript
+ * import Component from "@glimmer/component";
+ * import { block } from "discourse/blocks";
+ *
+ * @block("my-block")
+ * export default class MyBlock extends Component {
+ *   // ...
+ * }
+ * ```
+ *
+ * 2. Add an export to this file:
+ *
+ * ```javascript
+ * export { default as MyBlock } from "discourse/blocks/builtin/my-block";
+ * ```
+ *
+ * The initializer automatically picks up any new exports and registers them.
+ */
 export { default as BlockHead } from "./block-head";
 export { default as BlockGroup } from "./block-group";
 //# sourceMappingURL=index.d.ts.map

package/declarations/app/blocks/builtin/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/builtin/index.js"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/builtin/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,eAAe,CAAC"}

package/declarations/app/blocks/conditions/condition.d.ts

@@ -1,3 +1,52 @@
+import type { ArgSchema, BlockConstraints } from "discourse/blocks/types";
+import type { DebugLoggerInterface } from "discourse/lib/blocks/-internals/debug-hooks";
+/**
+ * Declares how a condition handles the `source` parameter.
+ *
+ * - `"none"`: `source` parameter is disallowed.
+ * - `"outletArgs"`: `source` must be `@outletArgs.propertyPath`; the base
+ *   class resolves it via outlet args.
+ * - `"object"`: `source` is passed directly as an object (e.g., for settings).
+ */
+export type ConditionSourceType = "none" | "outletArgs" | "object";
+/**
+ * Custom validation function for a condition, run at registration time
+ * against the condition's resolved args. Returns an error message (or
+ * messages), or `null`/`undefined` when the args are valid.
+ */
+export type ConditionValidateFn = (args: Record<string, unknown>) => string | string[] | null | undefined;
+/**
+ * Evaluation context passed to `evaluate()`, `resolveSource()`, and
+ * `getResolvedValueForLogging()`. Built by the block render pipeline (and,
+ * for nested route params, by the route condition itself).
+ */
+export interface ConditionContext {
+    /** Whether debug logging is enabled for this evaluation. */
+    debug?: boolean;
+    /** Outlet args passed to the block, used to resolve `@outletArgs.*` sources. */
+    outletArgs?: Record<string, unknown>;
+    /** Current nesting depth, used for debug log indentation. */
+    _depth?: number;
+    /** Logger interface for nested debug logging (used by the route condition
+     *  to log its OR/NOT/param sub-checks). */
+    logger?: DebugLoggerInterface | null;
+}
+/**
+ * Resolved-value info returned by `getResolvedValueForLogging()`, shown in
+ * the dev-tools debug overlay. Conditions that don't resolve a value (e.g.
+ * because `source` wasn't provided) return `undefined` instead.
+ */
+export interface ConditionResolvedValue {
+    /** Always `true` when a value was resolved. */
+    hasValue: true;
+    /** The resolved value, for conditions that resolve via `source`. */
+    value?: unknown;
+    /** An additional annotation, e.g. a "did you mean" note for an unknown setting. */
+    note?: string;
+    /** An alternate formatted payload, for conditions with non-`source`
+     *  resolution (e.g. the `outletArg` condition's `path`/`actual`/`configured` triple). */
+    formatted?: unknown;
+}
 /**
  * Base class for all block conditions.
  *
@@ -33,8 +82,6 @@
  * @experimental This API is under active development and may change or be removed
  * in future releases without prior notice. Use with caution in production environments.
  *
- * @class BlockCondition
- *
  * @example
  * ```javascript
  * import { blockCondition, BlockCondition } from "discourse/blocks/conditions";
@@ -65,15 +112,13 @@
  * }
  * ```
  */
-export class BlockCondition {
+export declare class BlockCondition {
     /**
      * Unique identifier for this condition type.
      * Used in condition specs: `{ type: "route", ... }`
      *
      * This property is defined by the `@blockCondition` decorator and should not
      * be set directly. Pass the `type` option to the decorator instead.
-     *
-     * @type {string}
      */
     static type: string;
     /**
@@ -85,40 +130,32 @@ export class BlockCondition {
      *
      * This property is defined by the `@blockCondition` decorator and should not
      * be set directly. Pass the `sourceType` option to the decorator instead.
-     *
-     * @type {"none" | "outletArgs" | "object"}
      */
-    static sourceType: "none" | "outletArgs" | "object";
+    static sourceType: ConditionSourceType;
     /**
      * Arg schema definitions for this condition.
      *
      * This property is defined by the `@blockCondition` decorator and should not
      * be overridden directly. The decorator creates a non-configurable getter
      * that returns a frozen object.
-     *
-     * @type {Object}
      */
-    static argsSchema: any;
+    static argsSchema: Readonly<Record<string, ArgSchema>>;
     /**
      * Cross-arg constraint definitions for this condition.
      *
      * This property is defined by the `@blockCondition` decorator and should not
      * be overridden directly. The decorator creates a non-configurable getter
      * that returns a frozen object or undefined.
-     *
-     * @type {Object|undefined}
      */
-    static constraints: any | undefined;
+    static constraints: Readonly<BlockConstraints> | undefined;
     /**
      * Custom validation function for this condition.
      *
      * This property is defined by the `@blockCondition` decorator and should not
      * be overridden directly. The decorator creates a non-configurable getter
      * that returns the validate function or undefined.
-     *
-     * @type {Function|undefined}
      */
-    static validateFn: Function | undefined;
+    static validateFn: ConditionValidateFn | undefined;
     /**
      * Valid argument keys for this condition.
      *
@@ -127,8 +164,6 @@ export class BlockCondition {
      *
      * The `source` key is automatically added by the decorator when
      * `sourceType !== "none"`.
-     *
-     * @type {readonly string[]}
      */
     static validArgKeys: readonly string[];
     /**
@@ -138,29 +173,24 @@ export class BlockCondition {
      *   and retrieves the corresponding value from `context.outletArgs`.
      * - `sourceType: "object"`: Returns the `source` value directly.
      *
-     * @param {Object} args - The condition arguments containing `source`.
-     * @param {Object} context - Evaluation context containing `outletArgs`.
-     * @param {Object} [context.outletArgs] - The outlet args passed to the block.
-     * @returns {*} The resolved value from outlet args, or undefined if not found.
+     * @param args - The condition arguments containing `source`.
+     * @param context - Evaluation context containing `outletArgs`.
+     * @returns The resolved value from outlet args, or undefined if not found.
      */
-    resolveSource(args: any, context: {
-        outletArgs?: any;
-    }): any;
+    resolveSource(args: Record<string, unknown>, context?: ConditionContext): unknown;
     /**
      * Default source value when `source` parameter is not provided.
      * Override in subclasses to provide a fallback (e.g., currentUser, siteSettings).
-     *
-     * @type {*}
      */
-    get defaultSource(): any;
+    get defaultSource(): unknown;
     /**
      * Resolves the source value, falling back to defaultSource when not provided.
      *
-     * @param {Object} args - The condition arguments.
-     * @param {Object} [context] - Evaluation context.
-     * @returns {*} The resolved source or defaultSource.
+     * @param args - The condition arguments.
+     * @param context - Evaluation context.
+     * @returns The resolved source or defaultSource.
      */
-    getSourceValue(args: any, context?: any): any;
+    getSourceValue(args: Record<string, unknown>, context?: ConditionContext): unknown;
     /**
      * Evaluates whether the condition passes.
      * Called at render time to determine if a block should be shown.
@@ -169,18 +199,11 @@ export class BlockCondition {
      * multiple times during a single render cycle (e.g., when debug logging
      * is enabled), and should not have side effects.
      *
-     * @param {Object} args - The condition arguments from the layout entry.
-     * @param {Object} [context] - Evaluation context from the blocks service.
-     * @param {boolean} [context.debug] - Whether debug logging is enabled.
-     * @param {Object} [context.outletArgs] - Outlet args for source resolution.
-     * @param {number} [context._depth] - Current nesting depth for logging.
-     * @returns {boolean} True if condition passes, false otherwise.
+     * @param args - The condition arguments from the layout entry.
+     * @param context - Evaluation context from the blocks service.
+     * @returns True if condition passes, false otherwise.
      */
-    evaluate(args: any, context?: {
-        debug?: boolean;
-        outletArgs?: any;
-        _depth?: number;
-    }): boolean;
+    evaluate(args: Record<string, unknown>, context?: ConditionContext): boolean;
     /**
      * Returns the resolved value for debug logging purposes.
      *
@@ -189,14 +212,10 @@ export class BlockCondition {
      * For example, the `outletArg` condition uses a `path` parameter
      * to resolve values from outlet args.
      *
-     * @param {Object} args - The condition arguments from the layout entry.
-     * @param {Object} [context] - Evaluation context containing outletArgs.
-     * @returns {{ value: *, hasValue: true }|undefined} Object with resolved value,
-     *   or undefined if this condition doesn't resolve values.
+     * @param args - The condition arguments from the layout entry.
+     * @param context - Evaluation context containing outletArgs.
+     * @returns Object with resolved value, or undefined if this condition doesn't resolve values.
      */
-    getResolvedValueForLogging(args: any, context?: any): {
-        value: any;
-        hasValue: true;
-    } | undefined;
+    getResolvedValueForLogging(args: Record<string, unknown>, context?: ConditionContext): ConditionResolvedValue | undefined;
 }
 //# sourceMappingURL=condition.d.ts.map

package/declarations/app/blocks/conditions/condition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"condition.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/conditions/condition.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH;IACE;;;;;;;;OAQG;IACH,aAFU,MAAM,CAEJ;IAEZ;;;;;;;;;;;OAWG;IACH,mBAFU,MAAM,GAAG,YAAY,GAAG,QAAQ,CAEf;IAE3B;;;;;;;;OAQG;IACH,uBAAkB;IAElB;;;;;;;;OAQG;IACH,oBAFU,MAAO,SAAS,CAEP;IAEnB;;;;;;;;OAQG;IACH,mBAFU,WAAS,SAAS,CAEV;IAElB;;;;;;;;;;OAUG;IACH,qBAFU,SAAS,MAAM,EAAE,CAEP;IAEpB;;;;;;;;;;;OAWG;IACH,kCAHG;QAAyB,UAAU;KACnC,GAAU,GAAC,CAuBb;IAED;;;;;OAKG;IACH,qBAFU,GAAC,CAIV;IAED;;;;;;OAMG;IACH,0CAFa,GAAC,CAMb;IAED;;;;;;;;;;;;;;OAcG;IAEH,8BANG;QAA0B,KAAK,GAAvB,OAAO;QACU,UAAU;QACV,MAAM,GAAvB,MAAM;KACd,GAAU,OAAO,CAKnB;IAED;;;;;;;;;;;;OAYG;IACH,sDAHa;QAAE,KAAK,EAAE,GAAC,CAAC;QAAC,QAAQ,EAAE,IAAI,CAAA;KAAE,GAAC,SAAS,CASlD;CACF"}
+{"version":3,"file":"condition.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/conditions/condition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6CAA6C,CAAC;AAExF;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEnE;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAErC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;+CAC2C;IAC3C,MAAM,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,+CAA+C;IAC/C,QAAQ,EAAE,IAAI,CAAC;IAEf,oEAAoE;IACpE,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;6FACyF;IACzF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,qBAAa,cAAc;IACzB;;;;;;OAMG;IACH,OAAe,IAAI,EAAE,MAAM,CAAC;IAE5B;;;;;;;;;OASG;IACH,MAAM,CAAC,UAAU,EAAE,mBAAmB,CAAU;IAEhD;;;;;;OAMG;IACH,OAAe,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IAE/D;;;;;;OAMG;IACH,OAAe,WAAW,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,SAAS,CAAC;IAEnE;;;;;;OAMG;IACH,OAAe,UAAU,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAE3D;;;;;;;;OAQG;IACH,OAAe,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAE/C;;;;;;;;;;OAUG;IACH,aAAa,CACX,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO;IAyBV;;;OAGG;IACH,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED;;;;;;OAMG;IACH,cAAc,CACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO;IAMV;;;;;;;;;;;OAWG;IAEH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO;IAI5E;;;;;;;;;;;OAWG;IACH,0BAA0B,CACxB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,gBAAgB,GACzB,sBAAsB,GAAG,SAAS;CAOtC"}

package/declarations/app/blocks/conditions/decorator.d.ts

@@ -1,14 +1,33 @@
+import type { ArgSchema, BlockConstraints } from "discourse/blocks/types";
+import { BlockCondition, type ConditionSourceType, type ConditionValidateFn } from "./condition";
 /**
- * Checks if a class was decorated with @blockCondition.
+ * Checks if a class was decorated with `@blockCondition`.
  * Used by the block registration system to reject non-decorated classes.
  *
  * @experimental This API is under active development and may change or be removed
  * in future releases without prior notice. Use with caution in production environments.
  *
- * @param {Function} ConditionClass - The class to check.
- * @returns {boolean} True if the class was decorated.
+ * @param ConditionClass - The class to check. Widened to `object` (rather than
+ *   a condition-class type) because this is also probed defensively before a
+ *   class is known to extend `BlockCondition`.
+ * @returns True if the class was decorated.
  */
-export function isDecoratedCondition(ConditionClass: Function): boolean;
+export declare function isDecoratedCondition(ConditionClass: object): boolean;
+/** Configuration accepted by the `@blockCondition` decorator. */
+export interface BlockConditionConfig {
+    /** Unique condition type identifier. */
+    type: string;
+    /** How the `source` parameter is handled. Defaults to `"none"`. */
+    sourceType?: ConditionSourceType;
+    /** Arg schema definitions (type, required, min, max, pattern, etc.).
+     *  Use `{ type: "any" }` to allow any type. */
+    args?: Record<string, ArgSchema>;
+    /** Cross-arg constraints (atLeastOne, exactlyOne, allOrNone, atMostOne). */
+    constraints?: BlockConstraints;
+    /** Custom validation function called at registration time. Receives the
+     *  args object, returns an error string/array or null. */
+    validate?: ConditionValidateFn;
+}
 /**
  * Decorator to define a block condition with declarative arg validation.
  *
@@ -19,17 +38,10 @@ export function isDecoratedCondition(ConditionClass: Function): boolean;
  * @experimental This API is under active development and may change or be removed
  * in future releases without prior notice. Use with caution in production environments.
  *
- * @param {Object} config - Condition configuration.
- * @param {string} config.type - Unique condition type identifier.
- * @param {"none"|"outletArgs"|"object"} [config.sourceType="none"] - How source parameter is handled.
- * @param {Object} [config.args={}] - Arg schema definitions (type, required, min, max, pattern, etc.).
- *   Use `{ type: "any" }` to allow any type.
- * @param {Object} [config.constraints] - Cross-arg constraints (atLeastOne, exactlyOne, allOrNone, atMostOne).
- * @param {Function} [config.validate] - Custom validation function called at registration time.
- *   Receives args object, returns error string/array or null.
- * @throws {Error} If config is invalid or class doesn't extend BlockCondition.
+ * @throws Error If config is invalid or class doesn't extend BlockCondition.
  *
  * @example
+ * ```javascript
  * import { blockCondition, BlockCondition } from "discourse/blocks/conditions";
  *
  * @blockCondition({
@@ -52,8 +64,10 @@ export function isDecoratedCondition(ConditionClass: Function): boolean;
  *   @service currentUser;
  *   evaluate(args, context) { ... }
  * }
+ * ```
  *
  * @example
+ * ```javascript
  * // With constraints
  * @blockCondition({
  *   type: "setting",
@@ -68,12 +82,7 @@ export function isDecoratedCondition(ConditionClass: Function): boolean;
  *     atMostOne: ["enabled", "equals", "includes"],
  *   },
  * })
+ * ```
  */
-export function blockCondition(config: {
-    type: string;
-    sourceType?: "none" | "outletArgs" | "object";
-    args?: any;
-    constraints?: any;
-    validate?: Function;
-}): (TargetClass: any) => any;
+export declare function blockCondition(config: BlockConditionConfig): <T extends typeof BlockCondition>(TargetClass: T) => T;
 //# sourceMappingURL=decorator.d.ts.map

package/declarations/app/blocks/conditions/decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/conditions/decorator.js"],"names":[],"mappings":"AAmCA;;;;;;;;;GASG;AACH,gEAFa,OAAO,CAInB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,uCAjDG;IAAuB,IAAI,EAAnB,MAAM;IACgC,UAAU,GAAhD,MAAM,GAAC,YAAY,GAAC,QAAQ;IACZ,IAAI;IAEJ,WAAW;IACT,QAAQ;CAElC,IA6HyB,gBAAW,SA0BtC"}
+{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/conditions/decorator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAU1E,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACzB,MAAM,aAAa,CAAC;AA4BrB;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,iEAAiE;AACjE,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IAEb,mEAAmE;IACnE,UAAU,CAAC,EAAE,mBAAmB,CAAC;IAEjC;mDAC+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAEjC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAE/B;8DAC0D;IAC1D,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,oBAAoB,GAC3B,CAAC,CAAC,SAAS,OAAO,cAAc,EAAE,WAAW,EAAE,CAAC,KAAK,CAAC,CAiHxD"}

package/declarations/app/blocks/conditions/index.d.ts

@@ -1,5 +1,7 @@
 export { BlockCondition } from "./condition";
+export type { ConditionContext, ConditionResolvedValue, ConditionSourceType, ConditionValidateFn, } from "./condition";
 export { blockCondition } from "./decorator";
+export type { BlockConditionConfig } from "./decorator";
 export { default as BlockOutletArgCondition } from "./outlet-arg";
 export { default as BlockRouteCondition } from "./route";
 export { default as BlockUserCondition } from "./user";

package/declarations/app/blocks/conditions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/conditions/index.js"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/conditions/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAIxD,OAAO,EAAE,OAAO,IAAI,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,OAAO,IAAI,sBAAsB,EAAE,MAAM,YAAY,CAAC"}

package/declarations/app/blocks/conditions/outlet-arg.d.ts

@@ -1,18 +1,10 @@
+import { BlockCondition, type ConditionContext, type ConditionResolvedValue } from "./condition";
 /**
  * A condition that evaluates based on outlet arg values.
  *
  * Checks properties passed via `@outletArgs` on the BlockOutlet. Supports
  * dot-notation paths for nested properties and flexible value matching.
  *
- * @class BlockOutletArgCondition
- * @extends BlockCondition
- *
- * @param {string} path - Dot-notation path to the property (required).
- *   E.g., `"topic.closed"`, `"user.trust_level"`, `"category.id"`.
- * @param {*} [value] - Value to match against (see matching rules below).
- * @param {boolean} [exists] - If true, passes when property exists (not undefined);
- *   if false, passes when property is undefined.
- *
  * ## Value Matching Rules
  *
  * Uses the shared `matchValue` utility:
@@ -24,66 +16,55 @@
  * - **`{ any: [...] }`**: Passes if `actual` matches ANY spec in array (OR logic)
  *
  * @example
+ * ```
  * // Check if topic is closed
  * { type: "outlet-arg", path: "topic.closed", value: true }
+ * ```
  *
  * @example
+ * ```
  * // Check user trust level is 2 or higher
  * { type: "outlet-arg", path: "user.trust_level", value: [2, 3, 4] }
+ * ```
  *
  * @example
+ * ```
  * // Check category is one of several IDs
  * { type: "outlet-arg", path: "category.id", value: [1, 2, 3] }
+ * ```
  *
  * @example
+ * ```
  * // Check if topic property exists
  * { type: "outlet-arg", path: "topic", exists: true }
+ * ```
  *
  * @example
+ * ```
  * // Check topic is NOT closed
  * { type: "outlet-arg", path: "topic.closed", value: { not: true } }
+ * ```
  *
  * @example
+ * ```
  * // Check category slug matches pattern
  * { type: "outlet-arg", path: "category.slug", value: /^support/ }
+ * ```
  *
  * @example
+ * ```
  * // Check topic is closed OR archived (using any)
  * { type: "outlet-arg", path: "topic.closed", value: { any: [true, { not: false }] } }
+ * ```
  */
 export default class BlockOutletArgCondition extends BlockCondition {
     /**
      * Evaluates whether the outlet arg condition passes.
-     *
-     * @param {Object} args - The condition arguments.
-     * @param {Object} [context] - Evaluation context.
-     * @returns {boolean} True if the condition passes.
      */
-    evaluate(args: any, context?: any): boolean;
+    evaluate(args: Record<string, unknown>, context?: ConditionContext): boolean;
     /**
      * Returns the resolved value at the path for debug logging.
-     *
-     * @param {Object} args - The condition arguments containing `path`, `value`, `exists`.
-     * @param {Object} [context] - Evaluation context containing outletArgs.
-     * @returns {{
-     *   hasValue: true,
-     *   formatted: {
-     *     path: string,
-     *     actual: *,
-     *     configured: * | { exists: boolean }
-     *   }
-     * }} Object with formatted log data showing path, actual value, and configured expectation.
      */
-    getResolvedValueForLogging(args: any, context?: any): {
-        hasValue: true;
-        formatted: {
-            path: string;
-            actual: any;
-            configured: any | {
-                exists: boolean;
-            };
-        };
-    };
+    getResolvedValueForLogging(args: Record<string, unknown>, context?: ConditionContext): ConditionResolvedValue;
 }
-import { BlockCondition } from "./condition";
 //# sourceMappingURL=outlet-arg.d.ts.map

package/declarations/app/blocks/conditions/outlet-arg.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"outlet-arg.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/conditions/outlet-arg.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH;IAiCE;;;;;;OAMG;IACH,oCAFa,OAAO,CAiBnB;IAED;;;;;;;;;;;;;OAaG;IAEH,sDAVa;QACR,QAAQ,EAAE,IAAI,CAAC;QACf,SAAS,EAAE;YACT,IAAI,EAAE,MAAM,CAAC;YACb,MAAM,EAAE,GAAC,CAAC;YACV,UAAU,EAAE,GAAC,GAAG;gBAAE,MAAM,EAAE,OAAO,CAAA;aAAE,CAAA;SACpC,CAAA;KACF,CAaH;CACF;+BAjJ8B,aAAa"}
+{"version":3,"file":"outlet-arg.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/conditions/outlet-arg.ts"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC5B,MAAM,aAAa,CAAC;AAuBrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAmCH,MAAM,CAAC,OAAO,OAAO,uBAAwB,SAAQ,cAAc;IACjE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO;IAiB5E;;OAEG;IACH,0BAA0B,CACxB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,gBAAgB,GACzB,sBAAsB;CAW1B"}

package/declarations/app/blocks/conditions/route.d.ts

@@ -1,3 +1,6 @@
+import type RouterService from "@ember/routing/router-service";
+import type DiscoveryService from "discourse/services/discovery";
+import { BlockCondition, type ConditionContext } from "./condition";
 /**
  * A condition that evaluates based on the current URL path, semantic page types,
  * route parameters, and query parameters.
@@ -24,51 +27,52 @@
  * normalizing URLs before matching. Theme authors don't need to know if
  * Discourse runs on `/forum` or root - patterns like `/c/**` work everywhere.
  *
- * @class BlockRouteCondition
- * @extends BlockCondition
- *
- * @param {string[]} [urls] - URL patterns to match (passes if ANY match).
- * @param {string[]} [pages] - Page types to match (passes if ANY match).
- * @param {Object} [params] - Page parameters to match (only valid with `pages`).
- * @param {Object} [queryParams] - Query parameters to match. Note: queryParams alone
- *   is not sufficient - the condition requires `urls` or `pages` to match first.
- *   This creates implicit AND behavior between route and query params.
- *
  * @example
+ * ```
  * // Match category pages using page type
  * { type: "route", pages: ["CATEGORY_PAGES"] }
+ * ```
  *
  * @example
+ * ```
  * // Match category pages using URL pattern
  * { type: "route", urls: ["/c/**"] }
+ * ```
  *
  * @example
+ * ```
  * // Match multiple page types (OR logic)
  * { type: "route", pages: ["CATEGORY_PAGES", "TAG_PAGES"] }
+ * ```
  *
  * @example
+ * ```
  * // Match specific category by ID
  * { type: "route", pages: ["CATEGORY_PAGES"], params: { categoryId: 5 } }
+ * ```
  *
  * @example
+ * ```
  * // Match with query params
  * { type: "route", urls: ["/latest"], queryParams: { filter: "solved" } }
+ * ```
  *
  * @example
+ * ```
  * // Exclude pages using NOT combinator
  * { not: { type: "route", pages: ["ADMIN_PAGES"] } }
+ * ```
  */
 export default class BlockRouteCondition extends BlockCondition {
-    router: any;
-    discovery: any;
+    #private;
+    router: RouterService;
+    discovery: DiscoveryService;
     /**
      * Returns the current URL path, normalized for matching.
      *
      * Normalization strips the subfolder prefix, query strings, hash fragments,
      * and trailing slashes. This allows patterns to work consistently regardless
      * of Discourse's installation configuration.
-     *
-     * @returns {string} The normalized URL path.
      */
     get currentPath(): string;
     /**
@@ -84,13 +88,7 @@ export default class BlockRouteCondition extends BlockCondition {
      * will only pass if BOTH the route (via `urls` or `pages`) AND the queryParams
      * match. This is implicit AND behavior. To match only based on query parameters,
      * use `urls: ["**"]` to match all routes first.
-     *
-     * @param {Object} args - The condition arguments.
-     * @param {Object} [context={}] - Evaluation context (for debugging).
-     * @returns {boolean} True if the condition passes.
      */
-    evaluate(args: any, context?: any): boolean;
-    #private;
+    evaluate(args: Record<string, unknown>, context?: ConditionContext): boolean;
 }
-import { BlockCondition } from "./condition";
 //# sourceMappingURL=route.d.ts.map