@discourse/types 2026.1.0-c7e9cdd → 2026.3.0-d02b2966

package/declarations/app/blocks/block-outlet.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Clears all registered outlet layouts.
+ *
+ * USE ONLY FOR TESTING PURPOSES.
+ */
+export function _resetOutletLayoutsForTesting(): void;
+/**
+ * Returns the internal outlet layouts map for testing.
+ * Allows tests to access validation promises to verify error handling.
+ *
+ * USE ONLY FOR TESTING PURPOSES.
+ *
+ * @returns {Map<string, {validatedLayout: Promise<Array<Object>>}>} The outlet layouts map.
+ */
+export function _getOutletLayouts(): Map<string, {
+    validatedLayout: Promise<Array<any>>;
+}>;
+/**
+ * Registers an outlet layout (array of block entries) for a named outlet.
+ *
+ * This is the main entry point for plugins to render blocks in designated areas.
+ * Each outlet can only have one layout registered. Attempting to register a
+ * second layout throws an error.
+ *
+ * @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 {string} outletName - The outlet identifier (must be in BLOCK_OUTLETS).
+ * @param {Array<LayoutEntry>} layout - Array of block entries.
+ * @param {Object} [owner] - The application owner for service lookup (passed from plugin API).
+ * @param {Error|null} [callSiteError] - Pre-captured error for source-mapped stack traces.
+ *   When called via api.renderBlocks(), this is captured there to exclude the PluginApi wrapper.
+ * @returns {Promise<Array<Object>>} Promise resolving to the validated layout array.
+ * @throws {Error} If validation fails or outlet already has a layout.
+ *
+ * @example
+ * ```js
+ *
+ * api.renderBlocks("homepage-blocks", [
+ *   { block: HeroBanner, args: { title: "Welcome" } },
+ *   {
+ *     block: BlockGroup,
+ *     children: [
+ *       { block: FeatureCard, args: { icon: "star" } },
+ *       { block: FeatureCard, args: { icon: "heart" } },
+ *     ]
+ *   },
+ *   {
+ *     block: AdminBanner,
+ *     args: { title: "Admin Only" },
+ *     conditions: [
+ *       { type: "user", admin: true }
+ *     ]
+ *   }
+ * ]);
+ * ```
+ */
+export function _renderBlocks(outletName: string, layout: Array<LayoutEntry>, owner?: any, callSiteError?: Error | null): Promise<Array<any>>;
+/**
+ * Component signature for BlockOutlet.
+ *
+ * @typedef {Object} BlockOutletSignature
+ * @property {Object} Args
+ * @property {string} Args.name - The outlet name (must be in BLOCK_OUTLETS registry).
+ * @property {Object} [Args.outletArgs] - Arguments to pass to blocks rendered in this outlet.
+ * @property {Object} [Args.deprecatedArgs] - Deprecated args with deprecation warnings.
+ * @property {Object} Blocks
+ * @property {[hasLayout: boolean]} Blocks.before - Yields hasLayout flag before content.
+ * @property {[hasLayout: boolean]} Blocks.after - Yields hasLayout flag after content.
+ * @property {[error: Error]} Blocks.error - Yields error when validation fails.
+ */
+/**
+ * Root component for rendering registered blocks in a designated outlet.
+ *
+ * BlockOutlet serves as the entry point for the block rendering system. It:
+ * - Looks up registered layouts by outlet name
+ * - Renders blocks in a consistent wrapper structure
+ * - Provides named blocks (`<:before>`, `<:after>`) for conditional content
+ *
+ * Named blocks:
+ * - `<:before>` - Yields `hasLayout` boolean before block content.
+ * - `<:after>` - Yields `hasLayout` boolean after block content.
+ *
+ * @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.
+ *
+ * @extends {Component<BlockOutletSignature>}
+ *
+ * @example
+ * ```hbs
+ * <BlockOutlet @name="homepage-blocks">
+ *   <:after as |hasBlocks|>
+ *     {{#unless hasBlocks}}
+ *       <p>No blocks configured</p>
+ *     {{/unless}}
+ *   </:after>
+ * </BlockOutlet>
+ * ```
+ */
+export default class BlockOutlet extends Component<BlockOutletSignature> {
+    constructor(owner: any, args: any);
+    get validatedLayout(): Promise<any[]>;
+    /**
+     * Processes block entries and returns renderable components.
+     *
+     * @returns {Promise<{rawChildren: Array<Object>, showGhosts: boolean, showVisualOverlay: boolean, isLoggingEnabled: boolean}>|undefined}
+     */
+    get children(): Promise<{
+        rawChildren: Array<any>;
+        showGhosts: boolean;
+        showVisualOverlay: boolean;
+        isLoggingEnabled: boolean;
+    }> | undefined;
+    /**
+     * The locked outlet name, used for CSS class generation and config lookup.
+     *
+     * @returns {string}
+     */
+    get outletName(): string;
+    /**
+     * The component to render for outlet boundary debug info.
+     * Returns the OutletInfo component when debug mode is enabled, null otherwise.
+     *
+     * @returns {typeof Component|null}
+     */
+    get OutletInfoComponent(): typeof Component | null;
+    /**
+     * Combines `@outletArgs` with `@deprecatedArgs` for lazy evaluation.
+     *
+     * Outlet args are values passed from the parent template to blocks rendered
+     * in this outlet. They are separate from layout entry args and accessed via
+     * `@outletArgs` in block components.
+     *
+     * Deprecated args trigger a deprecation warning when accessed, helping
+     * migrate consumers away from renamed or removed outlet args.
+     *
+     * @returns {Object} Combined args object with lazy property getters
+     */
+    get outletArgsWithDeprecations(): any;
+    #private;
+}
+/**
+ * A block entry in a layout configuration.
+ */
+export type LayoutEntry = {
+    /**
+     * - The block component class (must use
+     */
+    block: typeof Component | string;
+};
+/**
+ * Component signature for BlockOutlet.
+ */
+export type BlockOutletSignature = {
+    Args: {
+        name: string;
+        outletArgs?: any;
+        deprecatedArgs?: any;
+    };
+    Blocks: {
+        before: [hasLayout: boolean];
+        after: [hasLayout: boolean];
+        error: [error: Error];
+    };
+};
+import Component from "@glimmer/component";
+//# sourceMappingURL=block-outlet.d.ts.map

package/declarations/app/blocks/block-outlet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-outlet.d.ts","sourceRoot":"","sources":["../../../../discourse/app/blocks/block-outlet.gjs"],"names":[],"mappings":"AAiuBA;;;;GAIG;AACH,sDAKC;AAED;;;;;;;GAOG;AACH,qCAFa,GAAG,CAAC,MAAM,EAAE;IAAC,eAAe,EAAE,OAAO,CAAC,KAAK,KAAQ,CAAC,CAAA;CAAC,CAAC,CAOlE;AA0KD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,0CA9BW,MAAM,UACN,KAAK,CAAC,WAAW,CAAC,+BAElB,KAAK,GAAC,IAAI,GAER,OAAO,CAAC,KAAK,KAAQ,CAAC,CAqElC;AAaD;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAUE,mCAWC;IAED,sCAEC;IAED;;;;OAIG;IACH,gBAFa,OAAO,CAAC;QAAC,WAAW,EAAE,KAAK,KAAQ,CAAC;QAAC,UAAU,EAAE,OAAO,CAAC;QAAC,iBAAiB,EAAE,OAAO,CAAC;QAAC,gBAAgB,EAAE,OAAO,CAAA;KAAC,CAAC,GAAC,SAAS,CAkDvI;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;IAED;;;;;OAKG;IACH,2BAFa,OAAO,SAAS,GAAC,IAAI,CAIjC;IAED;;;;;;;;;;;OAWG;IACH,sCAUC;;CAoFF;;;;;;;;WA9kBa,OAAO,SAAS,GAAG,MAAM;;;;;;UA0VpC;QAAwB,IAAI,EAAjB,MAAM;QACQ,UAAU;QACV,cAAc;KACvC;YACA;QAAwC,MAAM,EAAnC,CAAC,SAAS,EAAE,OAAO,CAAC;QACS,KAAK,EAAlC,CAAC,SAAS,EAAE,OAAO,CAAC;QACG,KAAK,EAA5B,CAAC,KAAK,EAAE,KAAK,CAAC;KAC3B;;sBAvYqB,oBAAoB"}

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

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ *
+ * The system wrapper provides standard BEM classes:
+ * - `{outletName}__block-container` - Standard container class
+ * - `{outletName}__block-container--{id}` - BEM modifier when entry has an `id`
+ *
+ * System args (curried at creation time, not passed from parent):
+ * - `@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);
+}
+import Component from "@glimmer/component";
+//# sourceMappingURL=block-group.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,67 @@
+/**
+ * A container block that renders only its first visible child.
+ *
+ * Use this for prioritized conditional rendering where you want fallback logic:
+ * show the first child whose conditions pass, ignore the rest. This is useful
+ * for "if X, else if Y, else Z" patterns.
+ *
+ * ## Debug Visual Overlay Handling
+ *
+ * Unlike most containers that render all their children, the head block
+ * intentionally only renders one child (the first visible one). This means
+ * the block must handle the debug visual overlay ghosts itself.
+ *
+ * The preprocessing phase passes ALL children that passed their conditions,
+ * plus ghost blocks for children that failed conditions. Since we choose to
+ * not display children 2+, we are responsible for:
+ *
+ * 1. Rendering ghosts for children that failed their own conditions
+ *    (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
+ *
+ * This ensures the debug overlay accurately shows why each child is or
+ * isn't visible.
+ *
+ * The system wrapper provides standard BEM classes:
+ * - `{outletName}__head` - Standard block class
+ *
+ * System args (curried at creation time, not passed from parent):
+ * - `@outletName` - The outlet identifier this block belongs to
+ * - `@outletArgs` - Outlet args available for condition evaluation and access
+ *
+ * @example
+ * ```javascript
+ * api.renderBlocks("category-sidebar-blocks", [
+ *   {
+ *     block: "head",
+ *     children: [
+ *       // Show support panel for support category
+ *       { block: InfoPanel, args: {...}, conditions: [{ type: "route", params: { categorySlug: "support" } }] },
+ *       // Show dev panel for dev categories
+ *       { block: InfoPanel, args: {...}, conditions: [{ type: "route", params: { categorySlug: "dev" } }] },
+ *       // Default fallback (no conditions = always matches)
+ *       { block: InfoPanel, args: {...} },
+ *     ],
+ *   },
+ * ]);
+ * ```
+ */
+export default class HeadBlock extends Component<any> {
+    constructor(owner: import("@ember/-internals/owner").default, args: any);
+    blocks: any;
+    /**
+     * 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>;
+    /**
+     * 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;
+}
+import Component from "@glimmer/component";
+//# sourceMappingURL=block-head.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/builtin/index.js"],"names":[],"mappings":""}

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

@@ -0,0 +1,202 @@
+/**
+ * Base class for all block conditions.
+ *
+ * Subclasses must:
+ * - Use the `@blockCondition` decorator with `type` and `args` schema config
+ * - Implement the `evaluate(args, context)` method
+ * - Optionally provide a `validate` function in the decorator config for custom validation
+ * - Optionally pass `sourceType` to the decorator to enable `source` parameter support
+ *
+ * Condition classes can inject services using `@service` decorator.
+ * The Blocks service sets the owner on condition instances, enabling dependency injection.
+ *
+ * ## Validation Flow
+ *
+ * Validation happens at block registration time in this order:
+ * 1. Unknown args are detected (typo detection with suggestions)
+ * 2. Arg values are validated against the `args` schema (type, min, max, pattern, etc.)
+ * 3. Constraints are validated (atLeastOne, exactlyOne, allOrNone, atMostOne)
+ * 4. Source parameter is validated (based on sourceType)
+ * 5. Custom `validate` function from decorator config is called (if provided)
+ *
+ * ## Source Parameter Support
+ *
+ * Conditions can declare support for the `source` parameter via `static sourceType`:
+ *
+ * - `"none"` (default): `source` parameter is disallowed
+ * - `"outletArgs"`: `source` must be `@outletArgs.propertyPath`; base class resolves it
+ * - `"object"`: `source` is passed directly as an object (e.g., for settings)
+ *
+ * When `sourceType` is `"outletArgs"`, use `resolveSource(args, context)` to get the
+ * resolved value from outlet args.
+ *
+ * @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";
+ *
+ * @blockCondition({
+ *   type: "my-condition",
+ *   sourceType: "outletArgs",
+ *   args: {
+ *     requiredArg: { type: "string", required: true },
+ *     optionalCount: { type: "number", min: 0, max: 10 },
+ *   },
+ *   validate(args) {
+ *     // Custom validation that can't be expressed in schema
+ *     if (args.requiredArg === "forbidden") {
+ *       return "requiredArg cannot be 'forbidden'";
+ *     }
+ *     return null;
+ *   }
+ * })
+ * export default class BlockMyCondition extends BlockCondition {
+ *   @service myService;
+ *
+ *   evaluate(args, context) {
+ *     // Get value from source (outlet args) or fall back to service
+ *     const value = this.resolveSource(args, context) ?? this.myService.defaultValue;
+ *     return this.myService.someCheck(value, args.requiredArg);
+ *   }
+ * }
+ * ```
+ */
+export 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;
+    /**
+     * Declares how this condition handles the `source` parameter.
+     *
+     * - `"none"` (default): `source` parameter is disallowed
+     * - `"outletArgs"`: `source` must be `@outletArgs.propertyPath`; base class resolves it
+     * - `"object"`: `source` is passed directly as an object (e.g., settings object)
+     *
+     * 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";
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Valid argument keys for this condition.
+     *
+     * This property is derived from the `args` schema by the `@blockCondition`
+     * decorator and should not be overridden directly.
+     *
+     * The `source` key is automatically added by the decorator when
+     * `sourceType !== "none"`.
+     *
+     * @type {readonly string[]}
+     */
+    static validArgKeys: readonly string[];
+    /**
+     * Resolves the `source` parameter value based on the condition's `sourceType`.
+     *
+     * - `sourceType: "outletArgs"`: Extracts the property path from `@outletArgs.path.to.value`
+     *   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.
+     */
+    resolveSource(args: any, context: {
+        outletArgs?: any;
+    }): any;
+    /**
+     * Default source value when `source` parameter is not provided.
+     * Override in subclasses to provide a fallback (e.g., currentUser, siteSettings).
+     *
+     * @type {*}
+     */
+    get defaultSource(): any;
+    /**
+     * 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.
+     */
+    getSourceValue(args: any, context?: any): any;
+    /**
+     * Evaluates whether the condition passes.
+     * Called at render time to determine if a block should be shown.
+     *
+     * **Note: This method MUST be pure and idempotent.** It may be called
+     * 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.
+     */
+    evaluate(args: any, context?: {
+        debug?: boolean;
+        outletArgs?: any;
+        _depth?: number;
+    }): boolean;
+    /**
+     * Returns the resolved value for debug logging purposes.
+     *
+     * Override this method in subclasses to provide custom resolved values
+     * for conditions that don't use the standard `source` parameter.
+     * 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.
+     */
+    getResolvedValueForLogging(args: any, context?: any): {
+        value: any;
+        hasValue: true;
+    } | undefined;
+}
+//# sourceMappingURL=condition.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,79 @@
+/**
+ * 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.
+ */
+export function isDecoratedCondition(ConditionClass: Function): boolean;
+/**
+ * Decorator to define a block condition with declarative arg validation.
+ *
+ * The class must extend BlockCondition. The decorator adds static getters
+ * for type, sourceType, argsSchema, constraints, validateFn, and validArgKeys
+ * based on the provided config. Unknown config keys are rejected with helpful suggestions.
+ *
+ * @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.
+ *
+ * @example
+ * import { blockCondition, BlockCondition } from "discourse/blocks/conditions";
+ *
+ * @blockCondition({
+ *   type: "user",
+ *   sourceType: "outletArgs",
+ *   args: {
+ *     loggedIn: { type: "boolean" },
+ *     admin: { type: "boolean" },
+ *     minTrustLevel: { type: "number", min: 0, max: 4, integer: true },
+ *     groups: { type: "array", itemType: "string" },
+ *   },
+ *   validate(args) {
+ *     if (args.loggedIn === false && args.admin) {
+ *       return "Cannot use loggedIn: false with admin condition.";
+ *     }
+ *     return null;
+ *   }
+ * })
+ * export default class BlockUserCondition extends BlockCondition {
+ *   @service currentUser;
+ *   evaluate(args, context) { ... }
+ * }
+ *
+ * @example
+ * // With constraints
+ * @blockCondition({
+ *   type: "setting",
+ *   sourceType: "object",
+ *   args: {
+ *     name: { type: "string", required: true },
+ *     enabled: { type: "boolean" },
+ *     equals: { type: "any" },
+ *     includes: { type: "array" },
+ *   },
+ *   constraints: {
+ *     atMostOne: ["enabled", "equals", "includes"],
+ *   },
+ * })
+ */
+export function blockCondition(config: {
+    type: string;
+    sourceType?: "none" | "outletArgs" | "object";
+    args?: any;
+    constraints?: any;
+    validate?: Function;
+}): (TargetClass: any) => any;
+//# sourceMappingURL=decorator.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,8 @@
+export { BlockCondition } from "./condition";
+export { blockCondition } from "./decorator";
+export { default as BlockOutletArgCondition } from "./outlet-arg";
+export { default as BlockRouteCondition } from "./route";
+export { default as BlockUserCondition } from "./user";
+export { default as BlockSettingCondition } from "./setting";
+export { default as BlockViewportCondition } from "./viewport";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/conditions/index.js"],"names":[],"mappings":""}

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

@@ -0,0 +1,89 @@
+/**
+ * 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:
+ *
+ * - **Primitive**: Passes if `actual === value` (strict equality)
+ * - **RegExp**: Passes if `actual` (coerced to string) matches the pattern
+ * - **[...values]**: Passes if `actual` matches ANY element (OR logic)
+ * - **`{ not: value }`**: Passes if `actual` does NOT match `value`
+ * - **`{ 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;
+    /**
+     * 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;
+            };
+        };
+    };
+}
+import { BlockCondition } from "./condition";
+//# sourceMappingURL=outlet-arg.d.ts.map

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

@@ -0,0 +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"}