@discourse/types 2026.8.0-fb9247e0 → 2026.9.0-c0ef3a11

package/declarations/app/lib/blocks/-internals/registry/helpers.d.ts

@@ -1,39 +1,52 @@
-/**
- * Asserts that a registry is not frozen before registration.
- *
- * @param {Object} options - Validation options.
- * @param {boolean} options.frozen - Whether the registry is frozen.
- * @param {string} options.apiMethod - The API method name for the error message.
- * @param {string} options.entityType - Type of entity (e.g., "Block", "Outlet", "Condition").
- * @param {string} options.entityName - Name of the entity being registered.
- * @returns {boolean} True if not frozen, false if frozen (error was raised).
- */
-export function assertRegistryNotFrozen({ frozen, apiMethod, entityType, entityName, }: {
+import { type CustomizationSource } from "discourse/lib/customization-source";
+/** Options for {@link assertRegistryNotFrozen}. */
+interface AssertRegistryNotFrozenOptions {
+    /** Whether the registry is frozen. */
     frozen: boolean;
+    /** The API method name for the error message. */
     apiMethod: string;
+    /** Type of entity (e.g., "Block", "Outlet", "Condition"). */
     entityType: string;
+    /** Name of the entity being registered. */
     entityName: string;
-}): boolean;
+}
+/**
+ * Asserts that a registry is not frozen before registration.
+ *
+ * @returns True if not frozen, false if frozen (error was raised).
+ */
+export declare function assertRegistryNotFrozen({ frozen, apiMethod, entityType, entityName, }: AssertRegistryNotFrozenOptions): boolean;
 /**
  * Validates that a name follows the namespaced block/outlet name pattern.
  *
  * Checks both the pattern format and maximum length to prevent memory and
  * performance issues from extremely long names.
  *
- * @param {string} name - The name to validate.
- * @param {string} entityType - Type of entity for error messages (e.g., "Block", "Outlet").
- * @returns {boolean} True if valid, false if invalid (error was raised).
+ * @param name - The name to validate.
+ * @param entityType - Type of entity for error messages (e.g., "Block", "Outlet").
+ * @returns True if valid, false if invalid (error was raised).
  */
-export function validateNamePattern(name: string, entityType: string): boolean;
+export declare function validateNamePattern(name: string, entityType: string): boolean;
 /**
  * Asserts that an entry is not already registered.
  *
- * @param {Map} registry - The registry to check.
- * @param {string} name - The name to check.
- * @param {string} entityType - Type of entity for error messages.
- * @returns {boolean} True if not duplicate, false if duplicate (error was raised).
+ * @param registry - The registry to check.
+ * @param name - The name to check.
+ * @param entityType - Type of entity for error messages.
+ * @returns True if not duplicate, false if duplicate (error was raised).
  */
-export function assertNotDuplicate(registry: Map<any, any>, name: string, entityType: string): boolean;
+export declare function assertNotDuplicate<V>(registry: Map<string, V>, name: string, entityType: string): boolean;
+/** Options for {@link validateSourceNamespace}. */
+interface ValidateSourceNamespaceOptions {
+    /** The name being registered. */
+    name: string;
+    /** Type of entity for error messages. */
+    entityType: "block" | "outlet" | "condition";
+    /** The plugin or theme the call came from. */
+    source?: CustomizationSource;
+    /** Whether to enforce single namespace per source. Defaults to `true`. */
+    enforceConsistency?: boolean;
+}
 /**
  * Validates that a block or outlet name follows namespace requirements for themes and plugins.
  *
@@ -42,46 +55,39 @@ export function assertNotDuplicate(registry: Map<any, any>, name: string, entity
  * - Plugins must use `namespace:name` format
  * - Optionally enforces that each source uses a consistent namespace across all registrations
  *
- * @param {Object} options - Validation options.
- * @param {string} options.name - The name being registered.
- * @param {"block"|"outlet"|"condition"} options.entityType - Type of entity for error messages.
- * @param {boolean} [options.enforceConsistency=true] - Whether to enforce single namespace per source.
- * @returns {boolean} True if validation passes, false if it failed (error was raised).
+ * @returns True if validation passes, false if it failed (error was raised).
  */
-export function validateSourceNamespace({ name, entityType, enforceConsistency, }: {
+export declare function validateSourceNamespace({ name, entityType, source, enforceConsistency, }: ValidateSourceNamespaceOptions): boolean;
+/** Options for {@link createTestRegistrationWrapper}. */
+interface TestRegistrationWrapperOptions {
+    /** Function to get frozen state. */
+    getFrozen: () => boolean;
+    /** Function to set frozen state. */
+    setFrozen: (value: boolean) => void;
+    /** Function to get saved test state. */
+    getSavedState: () => boolean | null;
+    /** Function to set saved test state. */
+    setSavedState: (value: boolean | null) => void;
+    /** Name for error message. */
     name: string;
-    entityType: "block" | "outlet" | "condition";
-    enforceConsistency?: boolean;
-}): boolean;
+}
 /**
  * Creates a test registration wrapper function for temporarily unfreezing a registry.
  *
  * USE ONLY FOR TESTING PURPOSES.
  *
- * @param {Object} options - Options object.
- * @param {() => boolean} options.getFrozen - Function to get frozen state.
- * @param {(value: boolean) => void} options.setFrozen - Function to set frozen state.
- * @param {() => boolean|null} options.getSavedState - Function to get saved test state.
- * @param {(value: boolean|null) => void} options.setSavedState - Function to set saved test state.
- * @param {string} options.name - Name for error message.
- * @returns {((callback: Function) => void)|undefined} The wrapper function.
+ * @returns The wrapper function, or `undefined` outside of `DEBUG` builds.
  */
-export function createTestRegistrationWrapper({ getFrozen, setFrozen, getSavedState, setSavedState, name, }: {
-    getFrozen: () => boolean;
-    setFrozen: (value: boolean) => void;
-    getSavedState: () => boolean | null;
-    setSavedState: (value: boolean | null) => void;
-    name: string;
-}): ((callback: Function) => void) | undefined;
+export declare function createTestRegistrationWrapper({ getFrozen, setFrozen, getSavedState, setSavedState, name, }: TestRegistrationWrapperOptions): ((callback: () => void) => void) | undefined;
 /**
  * Internal implementation for setting the test source identifier.
  *
  * USE ONLY FOR TESTING PURPOSES.
  *
- * @param {string|null} sourceId - Source identifier to use, or null to clear.
+ * @param sourceId - Source identifier to use, or null to clear.
  * @internal Called by `setTestSourceIdentifier` in block-testing.js.
  */
-export function _setTestSourceIdentifierInternal(sourceId: string | null): void;
+export declare function _setTestSourceIdentifierInternal(sourceId: string | null): void;
 /**
  * Resets the source namespace map and test source identifier.
  *
@@ -89,5 +95,6 @@ export function _setTestSourceIdentifierInternal(sourceId: string | null): void;
  *
  * @internal Called by `resetBlockRegistryForTesting`, not meant for direct use.
  */
-export function _resetSourceNamespaceState(): void;
+export declare function _resetSourceNamespaceState(): void;
+export {};
 //# sourceMappingURL=helpers.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/registry/helpers.js"],"names":[],"mappings":"AAgCA;;;;;;;;;GASG;AACH,wFANG;IAAyB,MAAM,EAAvB,OAAO;IACS,SAAS,EAAzB,MAAM;IACU,UAAU,EAA1B,MAAM;IACU,UAAU,EAA1B,MAAM;CACd,GAAU,OAAO,CAiBnB;AAED;;;;;;;;;GASG;AACH,0CAJW,MAAM,cACN,MAAM,GACJ,OAAO,CAsBnB;AAED;;;;;;;GAOG;AACH,kEAJW,MAAM,cACN,MAAM,GACJ,OAAO,CAQnB;AAED;;;;;;;;;;;;;GAaG;AACH,mFALG;IAAwB,IAAI,EAApB,MAAM;IACgC,UAAU,EAAhD,OAAO,GAAC,QAAQ,GAAC,WAAW;IACV,kBAAkB,GAApC,OAAO;CACf,GAAU,OAAO,CA6DnB;AAED;;;;;;;;;;;;GAYG;AACH,6GAPG;IAA+B,SAAS,EAAhC,MAAM,OAAO;IACqB,SAAS,EAA3C,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI;IACI,aAAa,EAAzC,MAAM,OAAO,GAAC,IAAI;IACqB,aAAa,EAApD,CAAC,KAAK,EAAE,OAAO,GAAC,IAAI,KAAK,IAAI;IACb,IAAI,EAApB,MAAM;CACd,GAAU,CAAC,CAAC,QAAQ,UAAU,KAAK,IAAI,CAAC,GAAC,SAAS,CA6BpD;AAuDD;;;;;;;GAOG;AACH,2DAHW,MAAM,GAAC,IAAI,QASrB;AAED;;;;;;GAMG;AACH,mDAUC"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/registry/helpers.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,oCAAoC,CAAC;AAoB5C,mDAAmD;AACnD,UAAU,8BAA8B;IACtC,sCAAsC;IACtC,MAAM,EAAE,OAAO,CAAC;IAEhB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAElB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IAEnB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,MAAM,EACN,SAAS,EACT,UAAU,EACV,UAAU,GACX,EAAE,8BAA8B,GAAG,OAAO,CAU1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAoB7E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,EACxB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,OAAO,CAMT;AAED,mDAAmD;AACnD,UAAU,8BAA8B;IACtC,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IAEb,yCAAyC;IACzC,UAAU,EAAE,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAC;IAE7C,8CAA8C;IAC9C,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAE7B,0EAA0E;IAC1E,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,IAAI,EACJ,UAAU,EACV,MAAM,EACN,kBAAyB,GAC1B,EAAE,8BAA8B,GAAG,OAAO,CA4D1C;AAED,yDAAyD;AACzD,UAAU,8BAA8B;IACtC,oCAAoC;IACpC,SAAS,EAAE,MAAM,OAAO,CAAC;IAEzB,oCAAoC;IACpC,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAEpC,wCAAwC;IACxC,aAAa,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;IAEpC,wCAAwC;IACxC,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,KAAK,IAAI,CAAC;IAE/C,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,EAC5C,SAAS,EACT,SAAS,EACT,aAAa,EACb,aAAa,EACb,IAAI,GACL,EAAE,8BAA8B,GAC7B,CAAC,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC,GAChC,SAAS,CAuBZ;AAgDD;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,IAAI,CAMN;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAUjD"}

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

@@ -1,39 +1,45 @@
-/**
- * Returns whether the outlet registry is frozen.
- *
- * @returns {boolean}
- */
-export function isOutletRegistryFrozen(): boolean;
+import type { CustomizationSource } from "discourse/lib/customization-source";
+/** Metadata recorded for a custom block outlet. */
+interface CustomOutletMetadata {
+    /** The outlet name. */
+    name: string;
+    /** Human-readable description. */
+    description?: string;
+}
+/** Returns whether the outlet registry is frozen. */
+export declare function isOutletRegistryFrozen(): boolean;
 /**
  * Returns all valid outlet names (both core and custom).
  *
- * @returns {string[]} Array of all outlet names.
+ * @returns Array of all outlet names.
  */
-export function getAllOutlets(): string[];
+export declare function getAllOutlets(): string[];
 /**
  * Checks if an outlet name is valid (registered as core or custom).
  *
- * @param {string} name - The outlet name to check.
- * @returns {boolean} True if the outlet is registered.
+ * @param name - The outlet name to check.
+ * @returns True if the outlet is registered.
  */
-export function isValidOutlet(name: string): boolean;
+export declare function isValidOutlet(name: string): boolean;
 /**
  * Gets metadata for a custom outlet.
  *
- * @param {string} name - The outlet name.
- * @returns {{ name: string, description?: string } | undefined} Outlet metadata or undefined.
+ * @param name - The outlet name.
+ * @returns Outlet metadata or undefined.
  */
-export function getCustomOutlet(name: string): {
-    name: string;
-    description?: string;
-} | undefined;
+export declare function getCustomOutlet(name: string): CustomOutletMetadata | undefined;
 /**
  * Freezes the outlet registry, preventing further registrations.
  * Called by the "freeze-block-registry" initializer during app boot.
  *
  * @internal
  */
-export function _freezeOutletRegistry(): void;
+export declare function _freezeOutletRegistry(): void;
+/** Options for {@link _registerOutlet}. */
+interface RegisterOutletOptions {
+    /** Human-readable description. */
+    description?: string;
+}
 /**
  * Registers a custom block outlet.
  *
@@ -42,15 +48,13 @@ export function _freezeOutletRegistry(): void;
  * - Plugin outlets: `namespace:outlet-name`
  * - Theme outlets: `theme:namespace:outlet-name`
  *
- * @param {string} outletName - The outlet name (must follow naming conventions).
- * @param {Object} [options] - Outlet options.
- * @param {string} [options.description] - Human-readable description.
+ * @param outletName - The outlet name (must follow naming conventions).
+ * @param options - Outlet options.
+ * @param source - The plugin or theme the call came from.
  *
  * @internal
  */
-export function _registerOutlet(outletName: string, options?: {
-    description?: string;
-}): void;
+export declare function _registerOutlet(outletName: string, options?: RegisterOutletOptions, source?: CustomizationSource): void;
 /**
  * Resets the outlet registry state for testing.
  *
@@ -58,5 +62,6 @@ export function _registerOutlet(outletName: string, options?: {
  *
  * @internal Called by `resetBlockRegistryForTesting`, not meant for direct use.
  */
-export function _resetOutletRegistryState(): void;
+export declare function _resetOutletRegistryState(): void;
+export {};
 //# sourceMappingURL=outlet.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"outlet.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/registry/outlet.js"],"names":[],"mappings":"AAgCA;;;;GAIG;AACH,0CAFa,OAAO,CAInB;AAED;;;;GAIG;AACH,iCAFa,MAAM,EAAE,CAIpB;AAED;;;;;GAKG;AACH,oCAHW,MAAM,GACJ,OAAO,CAInB;AAED;;;;;GAKG;AACH,sCAHW,MAAM,GACJ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAI9D;AAMD;;;;;GAKG;AACH,8CAEC;AAED;;;;;;;;;;;;;GAaG;AACH,4CANW,MAAM,YAEd;IAAyB,WAAW,GAA5B,MAAM;CAEd,QA8CF;AAMD;;;;;;GAMG;AACH,kDAUC"}
+{"version":3,"file":"outlet.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/registry/outlet.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAS9E,mDAAmD;AACnD,UAAU,oBAAoB;IAC5B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IAEb,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAmBD,qDAAqD;AACrD,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAExC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,GACX,oBAAoB,GAAG,SAAS,CAElC;AAMD;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED,2CAA2C;AAC3C,UAAU,qBAAqB;IAC7B,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,qBAA0B,EACnC,MAAM,CAAC,EAAE,mBAAmB,GAC3B,IAAI,CA6CN;AAMD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAUhD"}

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

@@ -0,0 +1,58 @@
+import type { ComponentLike } from "@glint/template";
+/**
+ * A block component class decorated with `@block`. Block metadata is stored in
+ * an internal WeakMap and read via `getBlockMetadata()`.
+ *
+ * Glimmer's `Component` is generic and invariant over its `Signature`, so
+ * neither `typeof Component` nor `Component<unknown>` accepts a concrete
+ * subclass like `class Foo extends Component<FooSignature>`. Since a block class
+ * is only ever stored, compared, and curried as an opaque token here — its
+ * component-ness is enforced at runtime by the `@block` decorator's
+ * `instanceof Component` check — a permissive construct signature is the
+ * idiomatic way to accept "any block component class".
+ */
+export type BlockClass = abstract new (...args: unknown[]) => object;
+/**
+ * A factory that lazily resolves to a block class (or a module whose default
+ * export is one), used for code-split block registration.
+ */
+export type BlockFactory = () => Promise<BlockClass | {
+    default: BlockClass;
+}>;
+/** A registry entry: either a resolved block class or a lazy factory. */
+export type BlockRegistryEntry = BlockClass | BlockFactory;
+/**
+ * A curried, render-ready block component. Curried components carry no
+ * statically known args, so this is intentionally a permissive `ComponentLike`.
+ */
+export type BlockComponent = ComponentLike;
+/**
+ * A block entry after preprocessing, carrying the visibility/keying metadata
+ * the render pipeline assigns (the `__`-prefixed fields).
+ */
+export interface BlockEntry {
+    block: string | BlockClass;
+    args?: Record<string, unknown>;
+    containerArgs?: Record<string, unknown>;
+    children?: BlockEntry[];
+    conditions?: object | object[];
+    classNames?: string;
+    id?: string;
+    __visible: boolean;
+    __stableKey: number;
+    __failureType?: string;
+    __failureReason?: string;
+}
+/**
+ * A renderable child produced by the block pipeline: the curried component, any
+ * `containerArgs` destined for the parent's `childArgs` schema, and a stable key
+ * for list rendering.
+ */
+export interface ChildBlockResult {
+    Component: BlockComponent;
+    containerArgs?: Record<string, unknown>;
+    key: string;
+    isGhost?: boolean;
+    asGhost: (reason: string) => ChildBlockResult | null;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../discourse/app/lib/blocks/-internals/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,CAAC;AAErE;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,UAAU,GAAG;IAAE,OAAO,EAAE,UAAU,CAAA;CAAE,CAAC,CAAC;AAE/E,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,YAAY,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,CAAC;AAE3C;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IAGZ,SAAS,EAAE,OAAO,CAAC;IAGnB,WAAW,EAAE,MAAM,CAAC;IAGpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,cAAc,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,GAAG,EAAE,MAAM,CAAC;IAGZ,OAAO,CAAC,EAAE,OAAO,CAAC;IAIlB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,gBAAgB,GAAG,IAAI,CAAC;CACtD"}

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

@@ -1,55 +1,66 @@
+import type { BlockClass } from "discourse/lib/blocks/-internals/types";
 /**
- * @typedef {Object} ValidationContext
- * @property {string} outletName - The name of the outlet being validated.
- * @property {string|null} [blockName=null] - The name of the block, if resolved.
- * @property {string} path - The hierarchical path to this entry (e.g., "layout[0].children[1]").
- * @property {Object|null} [entry=null] - The block entry object being validated.
- * @property {Error|null} [callSiteError=null] - Error captured at the call site for stack traces.
- * @property {Array|null} [rootLayout=null] - The root layout array for error display.
- *
- * The following properties are added by validation code after initial context creation:
- * @property {string} [errorPath] - Full path to the error (e.g., "layout[0].conditions.params.categoryId").
- * @property {string} [conditionsPath] - Path within conditions (e.g., "params.categoryId").
- * @property {Object} [conditions] - The conditions object for error display.
+ * Parameters accepted by `createValidationContext()`.
  */
+export interface CreateValidationContextParams {
+    /** The name of the outlet being validated. */
+    outletName: string;
+    /** The name of the block, if resolved. */
+    blockName?: string | null;
+    /** The hierarchical path to this entry (e.g., "layout[0].children[1]"). */
+    path: string;
+    /** The block entry object being validated. */
+    entry?: Record<string, unknown> | null;
+    /** Error captured at the call site for stack traces. */
+    callSiteError?: Error | null;
+    /** The root layout array for error display. */
+    rootLayout?: Array<Record<string, unknown>> | null;
+}
+/**
+ * Validation context passed through the layout validation pipeline for error
+ * reporting. Created via `createValidationContext()` to ensure consistent
+ * structure across all validation functions; the members beyond the creation
+ * params are added by validation code after initial context creation.
+ */
+export interface ValidationContext extends CreateValidationContextParams {
+    /** Full path to the error (e.g., "layout[0].conditions.params.categoryId"). */
+    errorPath?: string;
+    /** Path within conditions (e.g., "params.categoryId"). */
+    conditionsPath?: string;
+    /** The conditions object for error display. */
+    conditions?: unknown;
+}
 /**
  * Creates a validation context object for error reporting.
  * Centralizes context creation to ensure consistent structure across
  * all validation functions.
- *
- * @param {Object} params - Context parameters.
- * @param {string} params.outletName - The name of the outlet being validated.
- * @param {string|null} [params.blockName=null] - The name of the block, if resolved.
- * @param {string} params.path - The hierarchical path to this entry.
- * @param {Object|null} [params.entry=null] - The block entry object being validated.
- * @param {Error|null} [params.callSiteError=null] - Error captured at the call site.
- * @param {Array|null} [params.rootLayout=null] - The root layout array for error display.
- * @returns {ValidationContext} A validation context object.
  */
-export function createValidationContext({ outletName, blockName, path, entry, callSiteError, rootLayout, }: {
-    outletName: string;
-    blockName?: string | null;
-    path: string;
-    entry?: any | null;
-    callSiteError?: Error | null;
-    rootLayout?: any[] | null;
-}): ValidationContext;
+export declare function createValidationContext({ outletName, blockName, path, entry, callSiteError, rootLayout, }: CreateValidationContextParams): ValidationContext;
 /**
  * Builds a hierarchical error path by joining path segments.
  * Used to construct full paths for error messages (e.g., "layout[0].args.title").
  *
- * @param {string} basePath - The base path (e.g., "layout[0]").
- * @param {string} segment - The segment to append (e.g., "args.title").
- * @returns {string} Combined path with dot separator, or the non-empty path if one is missing.
+ * @param basePath - The base path (e.g., "layout[0]").
+ * @param segment - The segment to append (e.g., "args.title").
+ * @returns Combined path with dot separator, or the non-empty path if one is missing.
  *
  * @example
+ * ```
  * buildErrorPath("layout[0]", "args.title")
  * // => "layout[0].args.title"
  *
  * buildErrorPath("", "args")
  * // => "args"
+ * ```
  */
-export function buildErrorPath(basePath: string, segment: string): string;
+export declare function buildErrorPath(basePath: string, segment: string): string;
+/**
+ * The `default` metadata for a single block argument, as read from the
+ * `@block` decorator's args schema.
+ */
+export interface BlockArgSchemaEntry {
+    default?: unknown;
+}
 /**
  * Applies default values from block metadata to provided args.
  *
@@ -57,9 +68,9 @@ export function buildErrorPath(basePath: string, segment: string): string;
  * args with default values from the block's metadata schema. Default values
  * are only applied when the arg is undefined in the provided args.
  *
- * @param {import("discourse/lib/blocks/-internals/registry/block").BlockClass} ComponentClass - The block component class.
- * @param {Object} providedArgs - The args provided in the layout entry.
- * @returns {Readonly<Object>} A new object with defaults applied for missing args.
+ * @param ComponentClass - The block component class.
+ * @param providedArgs - The args provided in the layout entry.
+ * @returns A new object with defaults applied for missing args.
  *
  * @example
  * ```javascript
@@ -68,7 +79,7 @@ export function buildErrorPath(basePath: string, segment: string): string;
  * // => { title: "Custom", count: 0 }
  * ```
  */
-export function applyArgDefaults(ComponentClass: import("discourse/lib/blocks/-internals/registry/block").BlockClass, providedArgs: any): Readonly<any>;
+export declare function applyArgDefaults(ComponentClass: BlockClass, providedArgs: Record<string, unknown>): Readonly<Record<string, unknown>>;
 /**
  * Performs a shallow comparison of two args objects.
  *
@@ -76,11 +87,11 @@ export function applyArgDefaults(ComponentClass: import("discourse/lib/blocks/-i
  * deep comparison of nested objects. Used to determine if cached curried
  * components can be reused.
  *
- * @param {Object|null|undefined} a - First args object.
- * @param {Object|null|undefined} b - Second args object.
- * @returns {boolean} True if the args are shallowly equal, false otherwise.
+ * @param a - First args object.
+ * @param b - Second args object.
+ * @returns True if the args are shallowly equal, false otherwise.
  */
-export function shallowArgsEqual(a: any | null | undefined, b: any | null | undefined): boolean;
+export declare function shallowArgsEqual(a: Record<string, unknown> | null | undefined, b: Record<string, unknown> | null | undefined): boolean;
 /**
  * Retrieves a value from a nested object using dot-notation path.
  *
@@ -88,57 +99,19 @@ export function shallowArgsEqual(a: any | null | undefined, b: any | null | unde
  * dot-separated path string. It handles null/undefined values gracefully
  * at any level of the path.
  *
- * @param {Object} obj - The object to get the value from.
- * @param {string} path - Dot-notation path (e.g., "user.trust_level").
- * @returns {*} The value at the path, or undefined if not found or if any
- *              intermediate value is null/undefined.
+ * @param obj - The object to get the value from.
+ * @param path - Dot-notation path (e.g., "user.trust_level").
+ * @returns The value at the path, or undefined if not found or if any
+ *   intermediate value is null/undefined.
  *
  * @example
+ * ```
  * const user = { profile: { name: "Alice", settings: { theme: "dark" } } };
  * getByPath(user, "profile.name"); // "Alice"
  * getByPath(user, "profile.settings.theme"); // "dark"
  * getByPath(user, "profile.missing"); // undefined
  * getByPath(user, "profile.settings.missing.deep"); // undefined (safe)
+ * ```
  */
-export function getByPath(obj: any, path: string): any;
-export type ValidationContext = {
-    /**
-     * - The name of the outlet being validated.
-     */
-    outletName: string;
-    /**
-     * - The name of the block, if resolved.
-     */
-    blockName?: string | null;
-    /**
-     * - The hierarchical path to this entry (e.g., "layout[0].children[1]").
-     */
-    path: string;
-    /**
-     * - The block entry object being validated.
-     */
-    entry?: any | null;
-    /**
-     * - Error captured at the call site for stack traces.
-     */
-    callSiteError?: Error | null;
-    /**
-     * - The root layout array for error display.
-     *
-     * The following properties are added by validation code after initial context creation:
-     */
-    rootLayout?: any[] | null;
-    /**
-     * - Full path to the error (e.g., "layout[0].conditions.params.categoryId").
-     */
-    errorPath?: string;
-    /**
-     * - Path within conditions (e.g., "params.categoryId").
-     */
-    conditionsPath?: string;
-    /**
-     * - The conditions object for error display.
-     */
-    conditions?: any;
-};
+export declare function getByPath(obj: unknown, path: string): unknown;
 //# sourceMappingURL=utils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../../../discourse/app/lib/blocks/-internals/utils.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;GAaG;AACH,4GARG;IAAuB,UAAU,EAAzB,MAAM;IACe,SAAS,GAA9B,MAAM,GAAC,IAAI;IACI,IAAI,EAAnB,MAAM;IACe,KAAK,GAA1B,MAAO,IAAI;IACS,aAAa,GAAjC,KAAK,GAAC,IAAI;IACU,UAAU,GAA9B,QAAM,IAAI;CAClB,GAAU,iBAAiB,CAW7B;AAED;;;;;;;;;;;;;;GAcG;AACH,yCAXW,MAAM,WACN,MAAM,GACJ,MAAM,CAiBlB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,iDAXW,OAAO,gDAAgD,EAAE,UAAU,sBAEjE,QAAQ,KAAQ,CAwB5B;AAED;;;;;;;;;;GAUG;AACH,oCAJW,MAAO,IAAI,GAAC,SAAS,KACrB,MAAO,IAAI,GAAC,SAAS,GACnB,OAAO,CAenB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,0CAXW,MAAM,GACJ,GAAC,CA0Bb;;;;;gBA/Ja,MAAM;;;;gBACN,MAAM,GAAC,IAAI;;;;UACX,MAAM;;;;YACN,MAAO,IAAI;;;;oBACX,KAAK,GAAC,IAAI;;;;;;iBACV,QAAM,IAAI;;;;gBAGV,MAAM;;;;qBACN,MAAM"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../../../discourse/app/lib/blocks/-internals/utils.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACvC,wDAAwD;IACxD,aAAa,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,+CAA+C;IAC/C,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CACpD;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAkB,SAAQ,6BAA6B;IACtE,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,UAAU,EACV,SAAgB,EAChB,IAAI,EACJ,KAAY,EACZ,aAAoB,EACpB,UAAiB,GAClB,EAAE,6BAA6B,GAAG,iBAAiB,CAEnD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQxE;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,UAAU,EAC1B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAkBnC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAC7C,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAC5C,OAAO,CAaT;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAgB7D"}