@discourse/types 2026.1.0-c7e9cdd → 2026.3.0-d02b2966

package/declarations/app/lib/blocks/-internals/debug-hooks.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Handles an optional missing block by logging and optionally creating a ghost.
+ *
+ * When a block reference ends with `?` but the block is not registered, this
+ * function handles the logging and ghost component creation.
+ *
+ * @param {Object} options - Options for handling the missing block.
+ * @param {string} options.blockName - The name of the missing block.
+ * @param {Object} options.entry - The block entry.
+ * @param {string} options.hierarchy - The hierarchy path for logging.
+ * @param {boolean} options.isLoggingEnabled - Whether debug logging is enabled.
+ * @param {boolean} options.showGhosts - Whether to show ghost components.
+ * @param {string} options.key - Stable unique key for this block.
+ * @returns {import("discourse/lib/blocks/-internals/entry-processing").ChildBlockResult|null}
+ *   Ghost component data with key if showGhosts is true, null otherwise.
+ */
+export function handleOptionalMissingBlock({ blockName, entry, hierarchy, isLoggingEnabled, showGhosts, key, }: {
+    blockName: string;
+    entry: any;
+    hierarchy: string;
+    isLoggingEnabled: boolean;
+    showGhosts: boolean;
+    key: string;
+}): import("discourse/lib/blocks/-internals/entry-processing").ChildBlockResult | null;
+/**
+ * Builds a container path for nested containers.
+ *
+ * Maintains a count map to ensure unique indices for containers of the same type.
+ * For example, if there are two "group" containers without ids, they get paths like:
+ * - `baseHierarchy/group[0]`
+ * - `baseHierarchy/group[1]`
+ *
+ * If a block has an id, it replaces the index (since the id is unique):
+ * - `baseHierarchy/group(#my-id)`
+ *
+ * @param {string} blockName - The block name.
+ * @param {string|null} blockId - The block's unique id (if set).
+ * @param {string} baseHierarchy - The base hierarchy path.
+ * @param {Map<string, number>} containerCounts - Map tracking container counts.
+ * @returns {string} The full container path.
+ */
+export function buildContainerPath(blockName: string, blockId: string | null, baseHierarchy: string, containerCounts: Map<string, number>): string;
+/**
+ * Invokes the BLOCK_DEBUG callback to create a ghost component.
+ *
+ * This is the low-level helper that calls the debug callback with block data.
+ * Used by both `createGhostBlock` (entry-processing time) and `asGhost`
+ * (render time) to avoid duplicating the callback invocation logic.
+ *
+ * @param {Object} blockData - Data describing the block to ghost.
+ * @param {string} blockData.name - The block name.
+ * @param {string} [blockData.id] - The block's unique ID (if set).
+ * @param {Object} [blockData.args] - Block arguments.
+ * @param {Object} [blockData.containerArgs] - Container arguments.
+ * @param {Array} [blockData.conditions] - Block conditions.
+ * @param {string} [blockData.failureType] - Type of failure (from FAILURE_TYPE).
+ * @param {string} [blockData.failureReason] - Custom failure reason message.
+ * @param {Array} [blockData.children] - Ghost children for containers.
+ * @param {Object} context - Context for the ghost.
+ * @param {string} context.outletName - The outlet/hierarchy name for display.
+ * @param {Object} [context.outletArgs] - Outlet arguments.
+ * @returns {Object|null} Ghost data with Component property, or null if callback
+ *   not set or didn't return a component.
+ */
+export function createDebugGhost(blockData: {
+    name: string;
+    id?: string;
+    args?: any;
+    containerArgs?: any;
+    conditions?: any[];
+    failureType?: string;
+    failureReason?: string;
+    children?: any[];
+}, context: {
+    outletName: string;
+    outletArgs?: any;
+}): any | null;
+/**
+ * Creates a ghost component for an invisible block.
+ *
+ * Ghost components are shown in debug mode to visualize blocks that failed
+ * their conditions or have no visible children.
+ *
+ * @param {Object} options - Options for creating the ghost.
+ * @param {string} options.blockName - The block name.
+ * @param {Object} options.entry - The block entry.
+ * @param {string} options.hierarchy - The hierarchy path for display.
+ * @param {string|undefined} options.containerPath - Container path for child hierarchies.
+ * @param {boolean} options.isContainer - Whether this block is a container.
+ * @param {import("@ember/owner").default} options.owner - The application owner.
+ * @param {Object} options.outletArgs - Outlet arguments.
+ * @param {boolean} options.isLoggingEnabled - Whether debug logging is enabled.
+ * @param {Function} options.resolveBlockFn - Function to resolve block references.
+ * @param {string} options.key - Stable unique key for this block.
+ * @returns {import("discourse/lib/blocks/-internals/entry-processing").ChildBlockResult|null}
+ *   Ghost component data with key if successful, null otherwise.
+ */
+export function createGhostBlock({ blockName, entry, hierarchy, containerPath, isContainer, owner, outletArgs, isLoggingEnabled, resolveBlockFn, key, }: {
+    blockName: string;
+    entry: any;
+    hierarchy: string;
+    containerPath: string | undefined;
+    isContainer: boolean;
+    owner: import("@ember/owner").default;
+    outletArgs: any;
+    isLoggingEnabled: boolean;
+    resolveBlockFn: Function;
+    key: string;
+}): import("discourse/lib/blocks/-internals/entry-processing").ChildBlockResult | null;
+/**
+ * Executes a function within a debug console group.
+ * Ensures START_GROUP and END_GROUP callbacks are always paired.
+ *
+ * @param {string} blockName - The block name for the group label.
+ * @param {string|null} blockId - The block's unique ID (if set).
+ * @param {string} hierarchy - The hierarchy path for context.
+ * @param {boolean} isLoggingEnabled - Whether debug logging is active.
+ * @param {() => boolean} fn - Function to execute that returns the condition result.
+ * @returns {boolean} The result of the function execution.
+ */
+export function withDebugGroup(blockName: string, blockId: string | null, hierarchy: string, isLoggingEnabled: boolean, fn: () => boolean): boolean;
+/**
+ * Callback key constants for the debug hooks registry.
+ * Use these instead of magic strings when calling debugHooks.getCallback/setCallback.
+ */
+export const DEBUG_CALLBACK: Readonly<{
+    BLOCK_DEBUG: "blockDebug";
+    BLOCK_LOGGING: "blockLogging";
+    VISUAL_OVERLAY: "visualOverlay";
+    GHOST_BLOCKS: "ghostBlocks";
+    OUTLET_INFO_COMPONENT: "outletInfoComponent";
+    CONDITION_LOG: "conditionLog";
+    COMBINATOR_LOG: "combinatorLog";
+    CONDITION_RESULT: "conditionResult";
+    PARAM_GROUP_LOG: "paramGroupLog";
+    ROUTE_STATE_LOG: "routeStateLog";
+    OPTIONAL_MISSING_LOG: "optionalMissingLog";
+    START_GROUP: "startGroup";
+    END_GROUP: "endGroup";
+    LOGGER_INTERFACE: "loggerInterface";
+    GHOST_CHILDREN_CREATOR: "ghostChildrenCreator";
+}>;
+/**
+ * Singleton instance of DebugHooks.
+ * Import this to access debug callbacks with tracked reactivity.
+ */
+export const debugHooks: DebugHooks;
+/**
+ * Singleton class that manages debug callback hooks for the block rendering system.
+ * Uses TrackedMap for reactivity, so components accessing these values will re-render
+ * when callbacks are set or cleared.
+ */
+declare class DebugHooks {
+    /**
+     * Gets a debug callback from the registry.
+     *
+     * @param {string} key - The callback key (use DEBUG_CALLBACK constants).
+     * @returns {Function|null} The callback function, or null if not set.
+     */
+    getCallback(key: string): Function | null;
+    /**
+     * Sets a debug callback in the registry.
+     * Used by dev-tools to register debug hooks.
+     *
+     * @param {string} key - The callback key (use DEBUG_CALLBACK constants).
+     * @param {Function|null} value - The callback function, or null to clear.
+     * @throws {Error} If the key is not a valid callback key.
+     */
+    setCallback(key: string, value: Function | null): void;
+    /**
+     * Returns whether console logging is enabled.
+     * Convenience getter that invokes the blockLogging callback.
+     *
+     * @returns {boolean} True if logging is enabled.
+     */
+    get isBlockLoggingEnabled(): boolean;
+    /**
+     * Returns the outlet info component if outlet boundaries are enabled.
+     * Invokes the OUTLET_INFO_COMPONENT callback which returns the component
+     * when enabled, or null when disabled.
+     *
+     * @returns {typeof import("@glimmer/component").default|null} The outlet info component, or null.
+     */
+    get outletInfoComponent(): typeof import("@glimmer/component").default | null;
+    /**
+     * Returns whether outlet boundaries should be shown.
+     * Derived from whether the outlet info component is available.
+     *
+     * @returns {boolean} True if boundaries should be shown.
+     */
+    get isOutletBoundaryEnabled(): boolean;
+    /**
+     * Returns whether visual overlay is enabled.
+     *
+     * @returns {boolean} True if visual overlay is enabled.
+     */
+    get isVisualOverlayEnabled(): boolean;
+    /**
+     * Returns whether ghost blocks are enabled.
+     *
+     * @returns {boolean} True if ghost blocks are enabled.
+     */
+    get isGhostBlocksEnabled(): boolean;
+    /**
+     * Returns the logger interface for conditions to use.
+     * Convenience getter that invokes the loggerInterface callback.
+     *
+     * The interface has methods: logCondition, updateCombinatorResult,
+     * updateConditionResult, logParamGroup, logRouteState.
+     *
+     * @returns {Object|null} The logger interface, or null if not available.
+     */
+    get loggerInterface(): any | null;
+    #private;
+}
+export {};
+//# sourceMappingURL=debug-hooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"debug-hooks.d.ts","sourceRoot":"","sources":["../../../../../../discourse/app/lib/blocks/-internals/debug-hooks.js"],"names":[],"mappings":"AAyJA;;;;;;;;;;;;;;;GAeG;AACH,gHATG;IAAwB,SAAS,EAAzB,MAAM;IACU,KAAK;IACL,SAAS,EAAzB,MAAM;IACW,gBAAgB,EAAjC,OAAO;IACU,UAAU,EAA3B,OAAO;IACS,GAAG,EAAnB,MAAM;CACd,GAAU,OAAO,kDAAkD,EAAE,gBAAgB,GAAC,IAAI,CAoC5F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,8CANW,MAAM,WACN,MAAM,GAAC,IAAI,iBACX,MAAM,mBACN,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GACjB,MAAM,CAelB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4CAdG;IAA0B,IAAI,EAAtB,MAAM;IACa,EAAE,GAArB,MAAM;IACa,IAAI;IACJ,aAAa;IACd,UAAU;IACT,WAAW,GAA9B,MAAM;IACa,aAAa,GAAhC,MAAM;IACY,QAAQ;CAClC,WACA;IAAwB,UAAU,EAA1B,MAAM;IACW,UAAU;CACnC,GAAU,MAAO,IAAI,CAcvB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,yJAbG;IAAwB,SAAS,EAAzB,MAAM;IACU,KAAK;IACL,SAAS,EAAzB,MAAM;IACoB,aAAa,EAAvC,MAAM,GAAC,SAAS;IACC,WAAW,EAA5B,OAAO;IACiC,KAAK,EAA7C,OAAO,cAAc,EAAE,OAAO;IACd,UAAU;IACT,gBAAgB,EAAjC,OAAO;IACW,cAAc;IAChB,GAAG,EAAnB,MAAM;CACd,GAAU,OAAO,kDAAkD,EAAE,gBAAgB,GAAC,IAAI,CAkD5F;AAED;;;;;;;;;;GAUG;AACH,0CAPW,MAAM,WACN,MAAM,GAAC,IAAI,aACX,MAAM,oBACN,OAAO,MACP,MAAM,OAAO,GACX,OAAO,CAqBnB;AAhWD;;;GAGG;AACH;;;;;;;;;;;;;;;;GAgBG;AA6GH;;;GAGG;AACH,oCAA2C;AA/G3C;;;;GAIG;AACH;IAWE;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,WAAS,IAAI,CAIzB;IAED;;;;;;;OAOG;IACH,iBAJW,MAAM,SACN,WAAS,IAAI,QAWvB;IAED;;;;;OAKG;IACH,6BAFa,OAAO,CAInB;IAED;;;;;;OAMG;IACH,2BAFa,cAAc,oBAAoB,EAAE,OAAO,GAAC,IAAI,CAI5D;IAED;;;;;OAKG;IACH,+BAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,8BAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,4BAFa,OAAO,CAInB;IAED;;;;;;;;OAQG;IACH,uBAFa,MAAO,IAAI,CAIvB;;CACF"}

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

@@ -0,0 +1,240 @@
+/**
+ * Registers a block class as the root block that can be rendered directly
+ * without authorization. Only one root block can be registered.
+ *
+ * @param {Function} klass - The block class to register as root.
+ */
+export function registerRootBlock(klass: Function): void;
+/**
+ * Schema for block argument validation.
+ *
+ * @typedef {Object} ArgSchema
+ * @property {"string"|"number"|"boolean"|"array"|"any"} type - The argument type (required)
+ * @property {boolean} [required=false] - Whether the argument is required
+ * @property {*} [default] - Default value for the argument
+ * @property {"string"|"number"|"boolean"} [itemType] - Item type for array arguments
+ * @property {RegExp} [pattern] - Regex pattern for string validation
+ * @property {number} [minLength] - Minimum length for string or array
+ * @property {number} [maxLength] - Maximum length for string or array
+ * @property {number} [min] - Minimum value for number
+ * @property {number} [max] - Maximum value for number
+ * @property {boolean} [integer] - Whether number must be an integer
+ * @property {Array} [enum] - Allowed values for the argument
+ * @property {Array} [itemEnum] - Allowed values for array items
+ */
+/**
+ * Decorator that transforms a Glimmer component into a block component.
+ *
+ * Block components have special authorization constraints:
+ * - They can only be rendered inside BlockOutlets or container blocks
+ * - They cannot be used directly in templates
+ * - They receive special args for authorization and hierarchy management
+ *
+ * @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} name - Unique identifier for the block. Supports three namespacing formats:
+ *   - Core blocks: `"block-name"` (e.g., "hero-banner", "sidebar-panel")
+ *   - Plugin blocks: `"plugin-name:block-name"` (e.g., "my-plugin:custom-card")
+ *   - Theme blocks: `"theme:theme-name:block-name"` (e.g., "theme:tactile:hero-section")
+ *   Names must use lowercase letters, numbers, and hyphens only.
+ *
+ * @param {Object} [options] - Configuration options for the block.
+ *
+ * @param {boolean} [options.container=false] - If true, this block can contain nested child blocks.
+ *
+ * @param {string} [options.description] - Human-readable description of the block.
+ *
+ * @param {Object.<string, ArgSchema>} [options.args] - Schema for block arguments.
+ *
+ * @param {Object.<string, ArgSchema>} [options.childArgs] - Schema for args passed to children
+ *   of this container block. Only valid when container: true.
+ *
+ * @param {Object} [options.constraints] - Cross-arg validation constraints.
+ *
+ * @param {Function} [options.validate] - Custom validation function.
+ *
+ * @param {string|string[]|((args: Object) => string)} [options.classNames] - Additional CSS classes.
+ *
+ * @param {string[]} [options.allowedOutlets] - Glob patterns for allowed outlets.
+ *
+ * @param {string[]} [options.deniedOutlets] - Glob patterns for denied outlets.
+ *
+ * @returns {Function} Decorator function that returns the decorated class
+ *
+ * @example
+ * // Simple block
+ * @block("my-card")
+ * class MyCard extends Component { ... }
+ *
+ * @example
+ * // Container block
+ * @block("my-section", { container: true })
+ * class MySection extends Component { ... }
+ *
+ */
+export function block(name: string, options?: {
+    container?: boolean;
+    description?: string;
+    args?: {
+        [x: string]: ArgSchema;
+    };
+    childArgs?: {
+        [x: string]: ArgSchema;
+    };
+    constraints?: any;
+    validate?: Function;
+    classNames?: string | string[] | ((args: any) => string);
+    allowedOutlets?: string[];
+    deniedOutlets?: string[];
+}): Function;
+/**
+ * Creates the args object for a child block with reactive getters for context args.
+ *
+ * This function embeds the AUTH_TOKEN in the __block$ property, which is how
+ * child blocks are authorized to render. The token is not exposed - it's
+ * embedded in the returned object.
+ *
+ * Context args are defined as getters rather than direct properties. This allows
+ * `curryComponent` to maintain a stable component identity while enabling reactive
+ * updates when the getter values change. Without getters, changing any arg would
+ * require creating a new curried component, breaking Ember's identity-based rendering.
+ *
+ * @param {Object} entryArgs - User-provided args from the layout entry.
+ * @param {Object} contextArgs - Rendering context to define as reactive getters.
+ * @returns {Object} The merged args object ready for `curryComponent`.
+ */
+export function createBlockArgsWithReactiveGetters(entryArgs: any, contextArgs: any): any;
+/**
+ * Gets all metadata for a component registered with @block.
+ *
+ * Returns a flat object containing all block information:
+ * - `blockName` - Full block name (e.g., "theme:my-theme:heading")
+ * - `shortName` - Plain name without namespace (e.g., "heading")
+ * - `namespace` - Full namespace for CSS ("my-plugin" or "theme-tactile") or null for core
+ * - `namespaceType` - "core" | "plugin" | "theme"
+ * - `isContainer` - Whether block is a container
+ * - `description` - Human-readable description
+ * - `decoratorClassNames` - CSS classNames from decorator
+ * - `args` - Args schema
+ * - `childArgs` - Child args schema (containers only)
+ * - `constraints` - Cross-arg validation constraints
+ * - `validate` - Custom validation function
+ * - `allowedOutlets` - Allowed outlet patterns
+ * - `deniedOutlets` - Denied outlet patterns
+ *
+ * @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} component - The component to get metadata for.
+ * @returns {Object|null} The block metadata object, or null if not a block.
+ */
+export function getBlockMetadata(component: Function): any | null;
+/**
+ * Schema for block argument validation.
+ */
+export type ArgSchema = {
+    /**
+     * - The argument type (required)
+     */
+    type: "string" | "number" | "boolean" | "array" | "any";
+    /**
+     * - Whether the argument is required
+     */
+    required?: boolean;
+    /**
+     * - Default value for the argument
+     */
+    default?: any;
+    /**
+     * - Item type for array arguments
+     */
+    itemType?: "string" | "number" | "boolean";
+    /**
+     * - Regex pattern for string validation
+     */
+    pattern?: RegExp;
+    /**
+     * - Minimum length for string or array
+     */
+    minLength?: number;
+    /**
+     * - Maximum length for string or array
+     */
+    maxLength?: number;
+    /**
+     * - Minimum value for number
+     */
+    min?: number;
+    /**
+     * - Maximum value for number
+     */
+    max?: number;
+    /**
+     * - Whether number must be an integer
+     */
+    integer?: boolean;
+    /**
+     * - Allowed values for the argument
+     */
+    enum?: any[];
+    /**
+     * - Allowed values for array items
+     */
+    itemEnum?: any[];
+};
+export type BlockMetadataEntry = {
+    /**
+     * - Whether the block is a container.
+     */
+    isContainer: boolean;
+    /**
+     * - The block's full name identifier (e.g., "theme:tactile:hero-banner").
+     */
+    blockName: string;
+    /**
+     * - The block's plain name without namespace (e.g., "hero-banner").
+     */
+    shortName: string;
+    /**
+     * - The parsed namespace for CSS (e.g., "my-plugin" or "theme-tactile").
+     */
+    namespace: string | null;
+    /**
+     * - The type of namespace.
+     */
+    namespaceType: "core" | "plugin" | "theme";
+    /**
+     * - Human-readable description of the block.
+     */
+    description: string;
+    /**
+     * - CSS classNames from decorator.
+     */
+    decoratorClassNames: string | string[] | Function | null;
+    /**
+     * - Args schema for the block.
+     */
+    args: any | null;
+    /**
+     * - Child args schema (containers only).
+     */
+    childArgs: any | null;
+    /**
+     * - Cross-arg validation constraints.
+     */
+    constraints: any | null;
+    /**
+     * - Custom validation function.
+     */
+    validate: Function | null;
+    /**
+     * - Allowed outlet patterns.
+     */
+    allowedOutlets: readonly string[] | null;
+    /**
+     * - Denied outlet patterns.
+     */
+    deniedOutlets: readonly string[] | null;
+};
+//# sourceMappingURL=decorator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../../../../../../discourse/app/lib/blocks/-internals/decorator.js"],"names":[],"mappings":"AA6FA;;;;;GAKG;AACH,yDAQC;AA8CD;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,4BAxCW,MAAM,YAQd;IAA0B,SAAS,GAA3B,OAAO;IAEU,WAAW,GAA5B,MAAM;IAE+B,IAAI,GAAzC;YAAQ,MAAM,GAAE,SAAS;KAAC;IAEW,SAAS,GAA9C;YAAQ,MAAM,GAAE,SAAS;KAAC;IAGT,WAAW;IAET,QAAQ;IAE0B,UAAU,GAA/D,MAAM,GAAC,MAAM,EAAE,GAAC,CAAC,CAAC,IAAI,KAAQ,KAAK,MAAM,CAAC;IAEvB,cAAc,GAAjC,MAAM,EAAE;IAEW,aAAa,GAAhC,MAAM,EAAE;CAEhB,YAoGF;AAED;;;;;;;;;;;;;;;GAeG;AACH,0FAoBC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,uDAFa,MAAO,IAAI,CAIvB;;;;;;;;UA1Na,QAAQ,GAAC,QAAQ,GAAC,SAAS,GAAC,OAAO,GAAC,KAAK;;;;eACzC,OAAO;;;;cACP,GAAC;;;;eACD,QAAQ,GAAC,QAAQ,GAAC,SAAS;;;;cAC3B,MAAM;;;;gBACN,MAAM;;;;gBACN,MAAM;;;;UACN,MAAM;;;;UACN,MAAM;;;;cACN,OAAO;;;;;;;;;;;;;;iBA3GP,OAAO;;;;eACP,MAAM;;;;eACN,MAAM;;;;eACN,MAAM,GAAC,IAAI;;;;mBACX,MAAM,GAAC,QAAQ,GAAC,OAAO;;;;iBACvB,MAAM;;;;yBACN,MAAM,GAAC,MAAM,EAAE,cAAU,IAAI;;;;UAC7B,MAAO,IAAI;;;;eACX,MAAO,IAAI;;;;iBACX,MAAO,IAAI;;;;cACX,WAAS,IAAI;;;;oBACb,SAAS,MAAM,EAAE,GAAC,IAAI;;;;mBACtB,SAAS,MAAM,EAAE,GAAC,IAAI"}

package/declarations/app/lib/blocks/-internals/entry-processing.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Processes block entries and creates renderable child components.
+ *
+ * This function iterates through a list of pre-processed block entries and
+ * transforms them into renderable components, handling ghost blocks for
+ * debug mode and optional missing blocks.
+ *
+ * @typedef {Object} BlockEntry
+ * @property {string|typeof import("@glimmer/component").default} block - Block reference (string name or class).
+ * @property {Object} [args] - Arguments to pass to the block.
+ * @property {Object} [containerArgs] - Values for parent container's childArgs schema.
+ * @property {Array<BlockEntry>} [children] - Nested block entries for containers.
+ * @property {Object|Array<Object>} [conditions] - Conditions that must pass for block to render.
+ * @property {string} [classNames] - Additional CSS classes for the block wrapper.
+ * @property {string} [id] - Unique identifier for BEM styling and targeting.
+ * @property {boolean} __visible - Whether the block passed condition evaluation.
+ * @property {number} __stableKey - Stable key assigned at registration time.
+ * @property {string} [__failureType] - The failure type constant (debug mode only).
+ * @property {string} [__failureReason] - Custom failure reason message (debug mode only).
+ *
+ * @typedef {Object} ChildBlockResult
+ * @property {import("ember-curry-component").CurriedComponent} Component - Curried component ready to render.
+ * @property {Object} [containerArgs] - Values for parent container's childArgs schema.
+ * @property {string} key - Stable unique key for list rendering.
+ * @property {boolean} [isGhost] - True if this is a ghost block (debug mode only).
+ * @property {(reason: string) => ChildBlockResult|null} [asGhost] - Returns a ghost version of this child with the given reason.
+ *   For regular children, creates a new ghost component (or null if debug mode is disabled).
+ *   For ghost children, returns self (no-op).
+ *
+ * @param {Object} options - Rendering options.
+ * @param {Array<BlockEntry>} options.entries - Pre-processed block entries with visibility metadata.
+ * @param {Map<string, {ComponentClass: typeof import("@glimmer/component").default, args: Object, result: ChildBlockResult}>} options.cache - Component cache keyed by stable block keys.
+ * @param {import("@ember/owner").default} options.owner - Application owner for service lookup.
+ * @param {string} options.baseHierarchy - Current hierarchy path (e.g., "homepage-blocks/section-1").
+ * @param {string} options.outletName - The outlet name for CSS class generation.
+ * @param {Object} options.outletArgs - Arguments passed from the outlet to blocks.
+ * @param {boolean} options.showGhosts - Whether to render ghost blocks for invisible entries.
+ * @param {boolean} options.isLoggingEnabled - Whether debug logging is active.
+ * @param {Function} options.createChildBlockFn - Function to create child block components (injected from block-outlet.gjs).
+ * @returns {Array<ChildBlockResult>} Array of renderable child objects with Component and containerArgs.
+ */
+export function processBlockEntries({ entries, cache, owner, baseHierarchy, outletName, outletArgs, showGhosts, isLoggingEnabled, createChildBlockFn, }: {
+    entries: Array<BlockEntry>;
+    cache: Map<string, {
+        ComponentClass: typeof import("@glimmer/component").default;
+        args: any;
+        result: ChildBlockResult;
+    }>;
+    owner: import("@ember/owner").default;
+    baseHierarchy: string;
+    outletName: string;
+    outletArgs: any;
+    showGhosts: boolean;
+    isLoggingEnabled: boolean;
+    createChildBlockFn: Function;
+}): Array<ChildBlockResult>;
+/**
+ * Processes block entries and creates renderable child components.
+ *
+ * This function iterates through a list of pre-processed block entries and
+ * transforms them into renderable components, handling ghost blocks for
+ * debug mode and optional missing blocks.
+ */
+export type BlockEntry = {
+    /**
+     * - Block reference (string name or class).
+     */
+    block: string | typeof import("@glimmer/component").default;
+    /**
+     * - Arguments to pass to the block.
+     */
+    args?: any;
+    /**
+     * - Values for parent container's childArgs schema.
+     */
+    containerArgs?: any;
+    /**
+     * - Nested block entries for containers.
+     */
+    children?: Array<BlockEntry>;
+    /**
+     * - Conditions that must pass for block to render.
+     */
+    conditions?: any | Array<any>;
+    /**
+     * - Additional CSS classes for the block wrapper.
+     */
+    classNames?: string;
+    /**
+     * - Unique identifier for BEM styling and targeting.
+     */
+    id?: string;
+    /**
+     * - Whether the block passed condition evaluation.
+     */
+    __visible: boolean;
+    /**
+     * - Stable key assigned at registration time.
+     */
+    __stableKey: number;
+    /**
+     * - The failure type constant (debug mode only).
+     */
+    __failureType?: string;
+    /**
+     * - Custom failure reason message (debug mode only).
+     */
+    __failureReason?: string;
+};
+/**
+ * Processes block entries and creates renderable child components.
+ *
+ * This function iterates through a list of pre-processed block entries and
+ * transforms them into renderable components, handling ghost blocks for
+ * debug mode and optional missing blocks.
+ */
+export type ChildBlockResult = {
+    /**
+     * - Curried component ready to render.
+     */
+    Component: any;
+    /**
+     * - Values for parent container's childArgs schema.
+     */
+    containerArgs?: any;
+    /**
+     * - Stable unique key for list rendering.
+     */
+    key: string;
+    /**
+     * - True if this is a ghost block (debug mode only).
+     */
+    isGhost?: boolean;
+    /**
+     * - Returns a ghost version of this child with the given reason.
+     * For regular children, creates a new ghost component (or null if debug mode is disabled).
+     * For ghost children, returns self (no-op).
+     */
+    asGhost?: (reason: string) => ChildBlockResult | null;
+};
+//# sourceMappingURL=entry-processing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entry-processing.d.ts","sourceRoot":"","sources":["../../../../../../discourse/app/lib/blocks/-internals/entry-processing.js"],"names":[],"mappings":"AA4FA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,yJAXG;IAAmC,OAAO,EAAlC,KAAK,CAAC,UAAU,CAAC;IAC2G,KAAK,EAAjI,GAAG,CAAC,MAAM,EAAE;QAAC,cAAc,EAAE,cAAc,oBAAoB,EAAE,OAAO,CAAC;QAAC,IAAI,MAAS;QAAC,MAAM,EAAE,gBAAgB,CAAA;KAAC,CAAC;IAC1E,KAAK,EAA7C,OAAO,cAAc,EAAE,OAAO;IACd,aAAa,EAA7B,MAAM;IACU,UAAU,EAA1B,MAAM;IACU,UAAU;IACT,UAAU,EAA3B,OAAO;IACU,gBAAgB,EAAjC,OAAO;IACW,kBAAkB;CAC5C,GAAU,KAAK,CAAC,gBAAgB,CAAC,CA0HnC;;;;;;;;;;;;WAzJa,MAAM,GAAC,cAAc,oBAAoB,EAAE,OAAO;;;;;;;;;;;;eAGlD,KAAK,CAAC,UAAU,CAAC;;;;iBACjB,MAAO,KAAK,KAAQ;;;;iBACpB,MAAM;;;;SACN,MAAM;;;;eACN,OAAO;;;;iBACP,MAAM;;;;oBACN,MAAM;;;;sBACN,MAAM;;;;;;;;;;;;;;;;;;;;;SAKN,MAAM;;;;cACN,OAAO;;;;;;cACP,CAAC,MAAM,EAAE,MAAM,KAAK,gBAAgB,GAAC,IAAI"}