A platform for community discussion. Free, open, simple.
DEV: Add plugin outlet aliases and deprecations (#38809)
Sérgio Saquetima373705c907e
diff --git a/config/locales/client.en.yml b/config/locales/client.en.ymlindex 2663043c77a..2c6e95cf55b 100644--- a/config/locales/client.en.yml+++ b/config/locales/client.en.yml@@ -395,6 +395,15 @@ en:visual_overlay: "Visual overlay"ghost_blocks: "Ghost blocks"condition_debugging: "Condition debugging"+ plugin_outlet_debug:+ find_on_github: "Find on GitHub"+ wrapper: "(wrapper)"+ outlet_args: "Outlet args"+ no_outlet_args: "No outlet args passed to this outlet"+ aliases: "Aliases"+ deprecated: "deprecated"+ deprecated_outlet: "This outlet is deprecated and will be removed."+ since: "(since %{version})"toggle_safe_mode: "Toggle safe mode"toggle_verbose_localization: "Toggle verbose localization"toggle_mobile_view: "Toggle mobile view"diff --git a/frontend/discourse/app/components/plugin-outlet.gjs b/frontend/discourse/app/components/plugin-outlet.gjsindex 60b4aade12a..d5aecf01759 100644--- a/frontend/discourse/app/components/plugin-outlet.gjs+++ b/frontend/discourse/app/components/plugin-outlet.gjs@@ -1,5 +1,6 @@/* eslint-disable ember/no-classic-components */import Component from "@glimmer/component";+import { DEBUG } from "@glimmer/env";import { cached } from "@glimmer/tracking";import ClassicComponent from "@ember/component";import { concat } from "@ember/helper";@@ -23,33 +24,325 @@ const GET_DEPRECATION_MSG =const ARGS_DEPRECATION_MSG ="PluginOutlet arguments should now be passed using `@outletArgs=` instead of `@args=`";-/**- A plugin outlet is an extension point for templates where other templates can- be inserted by plugins.+const DEPRECATION_ONLY_KEYS = ["since", "message", "id", "url", "raiseError"];+const VALID_POSITIONS = ["before", "after"];- ## Usage+/**+ * Normalizes an alias entry to a consistent object form.+ * Accepts either a plain string or an object with a `name` property.+ *+ * @param {string|Object} alias - The alias entry to normalize.+ * @returns {{ name: string, deprecated?: boolean, position?: string, since?: string, message?: string, id?: string, url?: string, raiseError?: boolean }}+ */+export function normalizeAlias(alias) {+ if (typeof alias === "string") {+ return { name: alias };+ }- If your handlebars template has:+ if (DEBUG) {+ if (!alias.name) {+ throw new Error("PluginOutlet alias object must have a `name` property.");+ }- ```handlebars- <PluginOutlet @name="evil-trout" />- ```+ if (alias.position && !VALID_POSITIONS.includes(alias.position)) {+ throw new Error(+ `PluginOutlet alias "${alias.name}" has invalid position "${alias.position}". ` ++ `Valid values are: ${VALID_POSITIONS.join(", ")}.`+ );+ }- Then any handlebars files you create in the `connectors/evil-trout` directory- will automatically be appended. For example:+ if (!alias.deprecated) {+ const presentKeys = DEPRECATION_ONLY_KEYS.filter(+ (key) => alias[key] != null+ );+ if (presentKeys.length > 0) {+ throw new Error(+ `PluginOutlet alias "${alias.name}" has deprecation properties (${presentKeys.join(", ")}) but \`deprecated\` is not true. ` ++ `Set \`deprecated=true\` or remove these properties.`+ );+ }+ }+ }- plugins/hello/assets/javascripts/discourse/templates/connectors/evil-trout/hello.hbs+ return alias;+}- With the contents:+/**+ * A plugin outlet is an extension point for templates where other templates can+ * be inserted by plugins.+ *+ * ## Standard vs wrapper outlets+ *+ * A **standard outlet** is an empty slot where connectors are inserted:+ *+ * ```handlebars+ * <PluginOutlet @name="above-footer" />+ * ```+ *+ * A **wrapper outlet** wraps existing content by providing a block. When a+ * connector is registered, it replaces the wrapped content. The outlet also+ * automatically creates `__before` and `__after` sub-outlets that allow+ * multiple connectors to render before or after the wrapped content without+ * replacing it:+ *+ * ```handlebars+ * <PluginOutlet @name="discovery-list-area">+ * <div class="default-content">This is the default content</div>+ * </PluginOutlet>+ * ```+ *+ * In this example, connectors can target:+ * - `discovery-list-area` to replace the default content+ * - `discovery-list-area__before` to render before it+ * - `discovery-list-area__after` to render after it+ *+ * ## Rendering connectors+ *+ * There are two ways to render content in a plugin outlet:+ *+ * ### 1. Plugin API (`api.renderInOutlet`)+ *+ * Register a component programmatically using the Plugin API:+ *+ * ```javascript+ * import MyComponent from "discourse/plugins/my-plugin/components/my-component";+ * api.renderInOutlet("evil-trout", MyComponent);+ * ```+ *+ * Or inline with gjs:+ *+ * ```javascript+ * api.renderInOutlet("evil-trout", <template><b>Hello World</b></template>);+ * ```+ *+ * For wrapper outlets, use `api.renderBeforeWrapperOutlet()` and+ * `api.renderAfterWrapperOutlet()` to render content before or after the+ * wrapped content without replacing it:+ *+ * ```javascript+ * api.renderBeforeWrapperOutlet("discovery-list-area", BeforeComponent);+ * api.renderAfterWrapperOutlet("discovery-list-area", AfterComponent);+ * ```+ *+ * ### 2. File-based connectors+ *+ * Create a template file in the `connectors/<outlet-name>/` directory:+ *+ * `plugins/my-plugin/assets/javascripts/discourse/connectors/evil-trout/hello.gjs`+ *+ * ```gjs+ * <template><b>Hello World</b></template>+ * ```+ *+ * This will render `<b>Hello World</b>` in every `<PluginOutlet @name="evil-trout" />`.+ *+ * For wrapper outlets, use the `__before` and `__after` suffixes in the+ * connector directory name:+ *+ * `plugins/my-plugin/assets/javascripts/discourse/connectors/discovery-list-area__before/my-connector.gjs`+ * `plugins/my-plugin/assets/javascripts/discourse/connectors/discovery-list-area__after/my-connector.gjs`+ *+ * ## Args+ *+ * See {@link PluginOutletSignature} for the full list of accepted args.+ *+ * Notes:+ * - Use `deprecatedOutletArgument()` to build entries for `@deprecatedArgs`.+ * - For `@aliases`, an entry may be a plain string (non-deprecated alias)+ * or a {@link PluginOutletAlias} object. Properties other than `name`,+ * `position`, and `deprecated` are only valid when `deprecated` is true —+ * a DEBUG-only assertion fires otherwise.+ * - The `id` on a {@link PluginOutletDeprecated} defaults to+ * `discourse.plugin-outlet.deprecated.<name>` if omitted.+ *+ * ## Examples+ *+ * ### Renaming an outlet (old name is deprecated)+ *+ * ```handlebars+ * <PluginOutlet+ * @name="new-outlet-name"+ * @aliases={{array+ * (hash name="old-outlet-name" deprecated=true since="2026.3.0")+ * }}+ * @outletArgs={{this.outletArgs}}+ * />+ * ```+ *+ * Connectors registered under `old-outlet-name` will render here and emit+ * a deprecation warning pointing to `new-outlet-name`.+ *+ * ### Non-deprecated alias+ *+ * ```handlebars+ * <PluginOutlet+ * @name="canonical-name"+ * @aliases={{array "alternate-name"}}+ * />+ * ```+ *+ * ### Merging a standalone outlet into a wrapper outlet's sub-outlet+ *+ * When a standalone outlet (e.g., `below-topic-list-item`) is being replaced by+ * a wrapper outlet, use `position="after"` (or `"before"`) to route connectors+ * from the old standalone outlet to the wrapper's `__after`/`__before`+ * sub-outlet:+ *+ * ```handlebars+ * <PluginOutlet+ * @name="topic-list-item__main-link-bottom-row"+ * @aliases={{array+ * (hash+ * name="below-topic-list-item-bottom-row"+ * position="after"+ * deprecated=true+ * since="2026.3.0"+ * )+ * }}+ * >+ * ...wrapped content...+ * </PluginOutlet>+ * ```+ *+ * Without `position`, alias connectors render in the main outlet (replacing+ * wrapped content). With `position="after"`, they render in the `__after`+ * sub-outlet instead, preserving the wrapped content. `position="before"`+ * works the same way for the `__before` sub-outlet.+ *+ * If the original standalone outlet declared a `@connectorTagName` (so that+ * legacy `.hbs` connectors received an automatic wrapper element), preserve+ * that behavior on the alias so existing connectors keep their wrapper:+ *+ * ```handlebars+ * <PluginOutlet+ * @name="latest-topic-list-item__post-count"+ * @aliases={{array+ * (hash+ * name="above-latest-topic-list-item-post-count"+ * position="before"+ * connectorTagName="div"+ * deprecated=true+ * since="2026.3.0"+ * )+ * }}+ * />+ * ```+ *+ * `connectorTagName` only applies to legacy file-based connectors registered+ * under the aliased name. Modern `.gjs` connectors control their own DOM and+ * ignore it.+ *+ * ### Deprecating an outlet entirely+ *+ * ```handlebars+ * <PluginOutlet+ * @name="doomed-outlet"+ * @deprecated={{hash since="2026.3.0" message="Use the Block API instead."}}+ * />+ * ```+ *+ * ### Deprecating an individual outlet argument+ *+ * Use `@deprecatedArgs` with `deprecatedOutletArgument()` to warn when a+ * specific arg is read by a connector, while keeping it functional until+ * connectors are migrated:+ *+ * ```gjs+ * import deprecatedOutletArgument from "discourse/helpers/deprecated-outlet-argument";+ *+ * <template>+ * <PluginOutlet+ * @name="my-outlet"+ * @outletArgs={{lazyHash newName=this.newName}}+ * @deprecatedArgs={{lazyHash+ * oldName=(deprecatedOutletArgument+ * value=this.newName+ * message="`oldName` is deprecated, use `newName` instead."+ * since="2026.3.0"+ * )+ * }}+ * />+ * </template>+ * ```+ *+ * ## Wrapper outlet alias behavior+ *+ * When a wrapper outlet has aliases, the `__before` and `__after` sub-outlets+ * automatically inherit them. For example, if outlet `foo` has alias `bar`,+ * then connectors registered under `bar__before` will render in `foo__before`,+ * and `bar__after` in `foo__after`.+ *+ * Aliases with a `position` property are an exception: they are routed to+ * the specified sub-outlet using their base name (not appended with+ * `__before`/`__after`), allowing standalone outlets to be merged into+ * a wrapper outlet's before or after slot.+ */- ```handlebars- <b>Hello World</b>- ```+/**+ * @typedef PluginOutletAlias+ *+ * @property {string} name The alias outlet name.+ * @property {boolean} [deprecated] Marks this alias as deprecated.+ * @property {"before"|"after"} [position] Routes the alias to a wrapper sub-outlet.+ * @property {string} [since] Discourse version when the deprecation was introduced.+ * @property {string} [message] Custom deprecation message.+ * @property {string} [id] Deprecation ID for silencing (auto-generated if omitted).+ * @property {string} [url] URL with more detail about the deprecation.+ * @property {boolean} [raiseError] Whether to throw instead of warn.+ * @property {string} [connectorTagName] HTML tag for legacy file-based connector+ * wrapper (e.g. `"div"`, `"span"`). Only relevant for position-targeted aliases+ * merging standalone outlets that had `@connectorTagName`.+ */- Will insert <b>Hello World</b> at that point in the template.+/**+ * @typedef PluginOutletDeprecated+ *+ * @property {string} [since] Version when the outlet was deprecated.+ * @property {string} [message] Custom deprecation message.+ * @property {string} [id] Deprecation ID.+ * @property {string} [url] URL with more detail about the deprecation.+ * @property {boolean} [raiseError] Whether to throw instead of warn.+ */-**/+/**+ * @typedef PluginOutletSignature+ *+ * @property {object} Args+ *+ * // Identity+ * @property {string} Args.name The outlet identifier. Connectors registered+ * under this name will be rendered here.+ *+ * // Args passed to connectors+ * @property {object} [Args.outletArgs] Arguments passed to connectors rendered+ * in this outlet.+ * @property {object} [Args.deprecatedArgs] Args with per-access deprecation+ * warnings. Build entries with `deprecatedOutletArgument()`.+ * @property {object} [Args.args] Deprecated legacy alias for `outletArgs`.+ *+ * // Aliases & deprecation+ * @property {Array<string|PluginOutletAlias>} [Args.aliases] Alternative outlet+ * names that this outlet also resolves connectors from. Useful for renaming+ * or merging outlets without breaking existing customizations.+ * @property {PluginOutletDeprecated} [Args.deprecated] Marks this outlet itself+ * as deprecated. When set, a deprecation warning is emitted if any connectors+ * are registered for this outlet.+ *+ * // Legacy file-based connector rendering+ * @property {string} [Args.tagName] HTML tag for the wrapper element rendered+ * around legacy file-based connectors.+ * @property {string} [Args.connectorTagName] HTML tag for legacy file-based+ * connector wrappers (e.g. `"div"`, `"span"`).+ * @property {boolean} [Args.defaultGlimmer] When true, file-based connectors+ * are rendered as template-only Glimmer components (no `this` context).+ *+ * // Optional wrapped content (wrapper outlets)+ * @property {object} Blocks+ * @property {[]} Blocks.default Default content rendered when no connector+ * replaces it.+ */+/** @extends {Component<PluginOutletSignature>} */export default class PluginOutlet extends Component {@service clientErrorHandler;@@ -75,14 +368,134 @@ export default class PluginOutlet extends Component {return result;}+ /**+ * Normalized alias entries from @aliases arg.+ * Each entry is an object with at least a `name` property.+ *+ * @returns {Array<{ name: string, deprecated?: boolean, since?: string, message?: string, id?: string, url?: string, raiseError?: boolean }>}+ */+ @cached+ get normalizedAliases() {+ if (!this.args.aliases?.length) {+ return [];+ }+ return this.args.aliases.map(normalizeAlias);+ }++ /**+ * Derived aliases for the __before sub-outlet.+ * Includes aliases with `position: "before"` using their base name (for merging+ * standalone outlets into a wrapper's before slot), plus `__before` variants+ * of all aliases without a position (for inheriting wrapper sub-outlet connectors).+ *+ * @returns {Array<Object>}+ */+ @cached+ get aliasesForBefore() {+ const result = [];+ for (const alias of this.normalizedAliases) {+ if (alias.position === "before") {+ // Strip position since routing is resolved -- the sub-outlet+ // should treat this as a regular alias+ const withoutPosition = { ...alias };+ delete withoutPosition.position;+ result.push(withoutPosition);+ } else if (!alias.position) {+ result.push({ ...alias, name: `${alias.name}__before` });+ }+ }+ return result;+ }++ /**+ * Derived aliases for the __after sub-outlet.+ * Includes aliases with `position: "after"` using their base name (for merging+ * standalone outlets into a wrapper's after slot), plus `__after` variants+ * of all aliases without a position (for inheriting wrapper sub-outlet connectors).+ *+ * @returns {Array<Object>}+ */+ @cached+ get aliasesForAfter() {+ const result = [];+ for (const alias of this.normalizedAliases) {+ if (alias.position === "after") {+ const withoutPosition = { ...alias };+ delete withoutPosition.position;+ result.push(withoutPosition);+ } else if (!alias.position) {+ result.push({ ...alias, name: `${alias.name}__after` });+ }+ }+ return result;+ }++ /**+ * The connector tag name inherited from a position-targeted alias routed+ * to the `__before` sub-outlet. Preserves the old standalone outlet's+ * `@connectorTagName` for legacy file-based connectors.+ *+ * @returns {string|undefined}+ */+ @cached+ get connectorTagNameForBefore() {+ for (const alias of this.normalizedAliases) {+ if (alias.position === "before" && alias.connectorTagName) {+ return alias.connectorTagName;+ }+ }+ return undefined;+ }++ /**+ * The connector tag name inherited from a position-targeted alias routed+ * to the `__after` sub-outlet. Preserves the old standalone outlet's+ * `@connectorTagName` for legacy file-based connectors.+ *+ * @returns {string|undefined}+ */+ @cached+ get connectorTagNameForAfter() {+ for (const alias of this.normalizedAliases) {+ if (alias.position === "after" && alias.connectorTagName) {+ return alias.connectorTagName;+ }+ }+ return undefined;+ }+@bindgetConnectors({ hasBlock } = {}) {- const connectors = renderedConnectorsFor(- this.args.name,- this.outletArgsWithDeprecations,- this.context,- getOwner(this)- );+ const aliases = this.normalizedAliases;+ const dep = this.args.deprecated;++ const connectors = this.#renderedConnectorsFor(this.args.name, {+ aliases,+ deprecated: dep,+ });++ // Emit outlet-level deprecation if connectors exist+ if (dep && connectors.length > 0) {+ this.#emitOutletDeprecation();+ }++ // Collect connectors from aliases (skip position-targeted aliases,+ // they are handled by the __before/__after sub-outlets)+ for (const alias of aliases) {+ if (alias.position) {+ continue;+ }+ const aliasConnectors = this.#renderedConnectorsFor(alias.name, {+ skipDebug: true,+ });+ if (aliasConnectors.length > 0) {+ if (alias.deprecated) {+ this.#emitAliasDeprecation(alias);+ }+ connectors.push(...aliasConnectors);+ }+ }+if (connectors.length > 1 && hasBlock) {const message = `Multiple connectors were registered for the ${this.args.name} outlet. Using the first.`;this.clientErrorHandler.displayErrorNotice(message);@@ -98,12 +511,36 @@ export default class PluginOutlet extends Component {@bindconnectorsExist({ hasBlock } = {}) {- return (- connectorsExist(this.args.name) ||+ if (+ this.#connectorsExistFor(this.args.name) ||(hasBlock &&- (connectorsExist(this.args.name + "__before") ||- connectorsExist(this.args.name + "__after")))- );+ (this.#connectorsExistFor(this.args.name + "__before") ||+ this.#connectorsExistFor(this.args.name + "__after")))+ ) {+ return true;+ }++ // Check aliases (position-targeted aliases are checked by sub-outlets,+ // but we still need to consider them for the wrapper's connectorsExist+ // since they make the wrapper render its content including sub-outlets)+ for (const alias of this.normalizedAliases) {+ if (alias.position) {+ if (this.#connectorsExistFor(alias.name)) {+ return true;+ }+ continue;+ }+ if (+ this.#connectorsExistFor(alias.name) ||+ (hasBlock &&+ (this.#connectorsExistFor(alias.name + "__before") ||+ this.#connectorsExistFor(alias.name + "__after")))+ ) {+ return true;+ }+ }++ return false;}// Traditionally, pluginOutlets had an argument named 'args'. However, that name is reserved@@ -149,11 +586,54 @@ export default class PluginOutlet extends Component {return curryComponent(component, args, getOwner(this));}+ #connectorsExistFor(name) {+ return connectorsExist(name);+ }++ #emitAliasDeprecation(alias) {+ const message =+ alias.message ||+ `Plugin outlet "${alias.name}" has been renamed to "${this.args.name}". Update your connector to use the new name.`;++ deprecated(message, {+ id: alias.id || `discourse.plugin-outlet.alias.${alias.name}`,+ since: alias.since,+ url: alias.url,+ raiseError: alias.raiseError,+ });+ }++ #emitOutletDeprecation() {+ const dep = this.args.deprecated;+ const message =+ dep.message ||+ `Plugin outlet "${this.args.name}" is deprecated and will be removed in a future version.`;++ deprecated(message, {+ id: dep.id || `discourse.plugin-outlet.deprecated.${this.args.name}`,+ since: dep.since,+ url: dep.url,+ raiseError: dep.raiseError,+ });+ }++ #renderedConnectorsFor(name, options) {+ return renderedConnectorsFor(+ name,+ this.outletArgsWithDeprecations,+ this.context,+ getOwner(this),+ options+ );+ }+<template>{{~#if (this.connectorsExist hasBlock=(has-block))~}}{{~#if (has-block)~}}<PluginOutlet@name={{concat @name "__before"}}+ @aliases={{this.aliasesForBefore}}+ @connectorTagName={{this.connectorTagNameForBefore}}@outletArgs={{this.outletArgsWithDeprecations}}/>{{~/if~}}@@ -192,6 +672,8 @@ export default class PluginOutlet extends Component {{{~#if (has-block)~}}<PluginOutlet@name={{concat @name "__after"}}+ @aliases={{this.aliasesForAfter}}+ @connectorTagName={{this.connectorTagNameForAfter}}@outletArgs={{this.outletArgsWithDeprecations}}/>{{~/if~}}diff --git a/frontend/discourse/app/components/topic-list/latest-topic-list-item.gjs b/frontend/discourse/app/components/topic-list/latest-topic-list-item.gjsindex 501524836da..de8bcd3cc8b 100644--- a/frontend/discourse/app/components/topic-list/latest-topic-list-item.gjs+++ b/frontend/discourse/app/components/topic-list/latest-topic-list-item.gjs@@ -1,5 +1,5 @@import Component from "@glimmer/component";-import { concat } from "@ember/helper";+import { array, concat, hash } from "@ember/helper";import PluginOutlet from "discourse/components/plugin-outlet";import ItemRepliesCell from "discourse/components/topic-list/item/replies-cell";import TopicPostBadges from "discourse/components/topic-post-badges";@@ -87,27 +87,35 @@ export default class LatestTopicListItem extends Component {<div class="bottom-row"><PluginOutlet@name="latest-topic-list-item-main-link-bottom-row"+ @aliases={{array+ (hash+ name="below-latest-topic-list-item-bottom-row"+ position="after"+ connectorTagName="span"+ deprecated=true+ since="2026.3.0"+ )+ }}@outletArgs={{lazyHash topic=@topic}}>{{categoryLink @topic.category~}}{{~discourseTags @topic mode="list"}}</PluginOutlet>- <PluginOutlet- @name="below-latest-topic-list-item-bottom-row"- @connectorTagName="span"- @outletArgs={{lazyHash topic=@topic}}- /></div></div><div class="topic-stats">- <PluginOutlet- @name="above-latest-topic-list-item-post-count"- @connectorTagName="div"- @outletArgs={{lazyHash topic=@topic}}- /><PluginOutlet@name="latest-topic-list-item-topic-stats"+ @aliases={{array+ (hash+ name="above-latest-topic-list-item-post-count"+ position="before"+ connectorTagName="div"+ deprecated=true+ since="2026.3.0"+ )+ }}@outletArgs={{lazyHash topic=@topic}}><ItemRepliesCell @topic={{@topic}} @tagName="div" />diff --git a/frontend/discourse/app/lib/plugin-connectors.js b/frontend/discourse/app/lib/plugin-connectors.jsindex e41358a5010..e335a9e7296 100644--- a/frontend/discourse/app/lib/plugin-connectors.js+++ b/frontend/discourse/app/lib/plugin-connectors.js@@ -212,20 +212,27 @@ export function connectorsExist(outletName) {return Boolean(_connectorCache[outletName] || debugOutletCallback);}-export function connectorsFor(outletName, outletArgs) {+export function connectorsFor(outletName, outletArgs, options) {if (!_connectorCache) {buildConnectorCache();}- if (debugOutletCallback) {+ if (debugOutletCallback && !options?.skipDebug) {return debugOutletCallback(outletName, _connectorCache[outletName], {outletArgs,+ ...options,});}return _connectorCache[outletName] || [];}-export function renderedConnectorsFor(outletName, args, context, owner) {- return connectorsFor(outletName, args).filter((con) => {+export function renderedConnectorsFor(+ outletName,+ args,+ context,+ owner,+ options+) {+ return connectorsFor(outletName, args, options).filter((con) => {return (!con.connectorClass?.shouldRender ||con.connectorClass?.shouldRender(args, context, owner)diff --git a/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/outlet-info.gjs b/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/outlet-info.gjsindex 9b3a53636b1..7ea3b21a5fe 100644--- a/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/outlet-info.gjs+++ b/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/outlet-info.gjs@@ -7,6 +7,8 @@ import DTooltip from "discourse/float-kit/components/d-tooltip";import concatClass from "discourse/helpers/concat-class";import icon from "discourse/helpers/d-icon";import { DEPRECATED_ARGS_KEY } from "discourse/lib/outlet-args";+import { or } from "discourse/truth-helpers";+import { i18n } from "discourse-i18n";import ArgsTable from "../shared/args-table";import devToolsState from "../state";@@ -31,6 +33,8 @@ const SMALL_OUTLETS = [* @param {string} outletName - The name of the plugin outlet.* @param {Object} [outletArgs] - Arguments passed to the outlet. May contain a non-enumerable* `__deprecatedArgs__` property with the raw deprecated args for display in the debug tooltip.+ * @param {Array<Object>} [aliases] - Normalized alias entries for this outlet.+ * @param {Object} [deprecated] - Deprecation info if the outlet itself is deprecated.*/export default class OutletInfoComponent extends Component {static shouldRender() {@@ -100,6 +104,24 @@ export default class OutletInfoComponent extends Component {);}+ /**+ * Whether this outlet has any aliases configured.+ *+ * @returns {boolean}+ */+ get hasAliases() {+ return this.args.aliases?.length > 0;+ }++ /**+ * Whether this outlet itself is deprecated.+ *+ * @returns {boolean}+ */+ get isDeprecated() {+ return !!this.args.deprecated;+ }+/*** Returns the heading modifier class based on outlet type.*@@ -149,7 +171,7 @@ export default class OutletInfoComponent extends Component {{{icon "plug"}}{{this.displayName}}{{#if this.partOfWrapper}}- (wrapper)+ {{i18n "js.dev_tools.plugin_outlet_debug.wrapper"}}{{/if}}</span><a@@ -157,18 +179,71 @@ export default class OutletInfoComponent extends Component {href="https://github.com/search?q=repo%3Adiscourse%2Fdiscourse%20@name=%22{{this.displayName}}%22&type=code"target="_blank"rel="noopener noreferrer"- title="Find on GitHub"+ title={{i18n "js.dev_tools.plugin_outlet_debug.find_on_github"}}>{{icon "fab-github"}}</a></div><div class="outlet-info__content">+ {{#if this.isDeprecated}}+ <div class="outlet-info__deprecation-banner">+ {{icon "triangle-exclamation"}}+ <span>+ {{or+ @deprecated.message+ (i18n+ "js.dev_tools.plugin_outlet_debug.deprecated_outlet"+ )+ }}+ {{#if @deprecated.since}}+ <span class="outlet-info__since">+ {{i18n+ "js.dev_tools.plugin_outlet_debug.since"+ }}+ </span>+ {{/if}}+ </span>+ </div>+ {{/if}}++ {{#if this.hasAliases}}+ <div class="outlet-info__section">+ <div class="outlet-info__section-title">+ {{i18n "js.dev_tools.plugin_outlet_debug.aliases"}}+ </div>+ <ul class="outlet-info__aliases">+ {{#each @aliases as |alias|}}+ <li class="outlet-info__alias">+ <code>{{alias.name}}</code>+ {{#if alias.deprecated}}+ <span class="outlet-info__alias-deprecated">+ {{icon "triangle-exclamation"}}+ {{i18n+ "js.dev_tools.plugin_outlet_debug.deprecated"+ }}+ {{#if alias.since}}+ {{i18n+ "js.dev_tools.plugin_outlet_debug.since"+ version=alias.since+ }}+ {{/if}}+ </span>+ {{/if}}+ </li>+ {{/each}}+ </ul>+ </div>+ {{/if}}+{{#if this.hasOutletArgs}}<div class="outlet-info__section">- <div class="outlet-info__section-title">Outlet Args</div>+ <div class="outlet-info__section-title">+ {{i18n "js.dev_tools.plugin_outlet_debug.outlet_args"}}+ </div><ArgsTable @args={{@outletArgs}} @prefix="plugin outlet" /></div>{{else}}<div class="outlet-info__empty">- No outlet args passed to this outlet+ {{i18n "js.dev_tools.plugin_outlet_debug.no_outlet_args"}}</div>{{/if}}</div>diff --git a/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/patch.js b/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/patch.jsindex fff18c402c2..b06d3874551 100644--- a/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/patch.js+++ b/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/patch.js@@ -14,23 +14,25 @@ export function patchConnectors() {// so ArgsTable can display deprecation info without separate prop passing_setIncludeDeprecatedArgsProperty(true);- _setOutletDebugCallback((outletName, existing, { outletArgs } = {}) => {- existing ||= [];+ _setOutletDebugCallback(+ (outletName, existing, { outletArgs, aliases, deprecated } = {}) => {+ existing ||= [];- if (!devToolsState.pluginOutletDebug) {- return existing;- }+ if (!devToolsState.pluginOutletDebug) {+ return existing;+ }- if (SKIP_EXISTING_FOR_OUTLETS.includes(outletName)) {- existing = [];- }+ if (SKIP_EXISTING_FOR_OUTLETS.includes(outletName)) {+ existing = [];+ }- const componentClass = curryComponent(- OutletInfoComponent,- { outletName, outletArgs },- getOwnerWithFallback()- );+ const componentClass = curryComponent(+ OutletInfoComponent,+ { outletName, outletArgs, aliases, deprecated },+ getOwnerWithFallback()+ );- return [{ componentClass }, ...existing];- });+ return [{ componentClass }, ...existing];+ }+ );}diff --git a/frontend/discourse/app/static/dev-tools/styles.css b/frontend/discourse/app/static/dev-tools/styles.cssindex ea94152e2d3..364043ed62a 100644--- a/frontend/discourse/app/static/dev-tools/styles.css+++ b/frontend/discourse/app/static/dev-tools/styles.css@@ -532,6 +532,62 @@ pre.outlet-info__error-message {overflow-y: auto;}+.outlet-info__deprecation-banner {+ display: flex;+ align-items: center;+ gap: 6px;+ padding: 6px 8px;+ background: var(--danger-low);+ border: 1px solid var(--danger-medium);+ border-radius: 4px;+ color: var(--danger);+ font-size: 12px;+ line-height: 1.4;++ .d-icon {+ flex-shrink: 0;+ }+}++.outlet-info__since {+ color: var(--primary-medium);+ font-size: 11px;+}++.outlet-info__aliases {+ list-style: none;+ margin: 0;+ padding: 0;+ display: flex;+ flex-direction: column;+ gap: 4px;++ code {+ font-size: 12px;+ padding: 1px 4px;+ background: var(--primary-very-low);+ border-radius: 3px;+ }+}++.outlet-info__alias {+ display: flex;+ align-items: center;+ gap: 6px;+}++.outlet-info__alias-deprecated {+ display: flex;+ align-items: center;+ gap: 4px;+ color: var(--danger);+ font-size: 11px;++ .d-icon {+ font-size: 10px;+ }+}+/* Shared Outlet Args Table */.outlet-args-table {display: flex;diff --git a/frontend/discourse/tests/integration/components/plugin-outlet-test.gjs b/frontend/discourse/tests/integration/components/plugin-outlet-test.gjsindex 2161f912540..76ca7f2d03d 100644--- a/frontend/discourse/tests/integration/components/plugin-outlet-test.gjs+++ b/frontend/discourse/tests/integration/components/plugin-outlet-test.gjs@@ -3,12 +3,15 @@ import Component from "@glimmer/component";import { tracked } from "@glimmer/tracking";import ClassicComponent from "@ember/component";import templateOnly from "@ember/component/template-only";+import { array, hash } from "@ember/helper";import { getOwner } from "@ember/owner";import { click, find, render, settled } from "@ember/test-helpers";import hbs from "htmlbars-inline-precompile";import { module, test } from "qunit";import sinon from "sinon";-import PluginOutlet from "discourse/components/plugin-outlet";+import PluginOutlet, {+ normalizeAlias,+} from "discourse/components/plugin-outlet";import deprecatedOutletArgument from "discourse/helpers/deprecated-outlet-argument";import lazyHash from "discourse/helpers/lazy-hash";import deprecated, {@@ -1292,3 +1295,551 @@ module(});});++module(+ "Integration | Component | plugin-outlet | aliases and deprecations",+ function (hooks) {+ setupRenderingTest(hooks);++ hooks.beforeEach(function () {+ this.consoleWarnStub = sinon.stub(console, "warn");+ disableRaiseOnDeprecation();+ });++ hooks.afterEach(function () {+ this.consoleWarnStub.restore();+ enableRaiseOnDeprecation();+ });++ test("renders connectors registered under an alias name", async function (assert) {+ extraConnectorComponent(+ "old-outlet-name",+ <template>+ <span class="alias-content">From alias</span>+ </template>+ );++ await render(+ <template>+ <PluginOutlet+ @name="new-outlet-name"+ @aliases={{array "old-outlet-name"}}+ />+ </template>+ );++ assert.dom(".alias-content").hasText("From alias");+ });++ test("renders connectors from both canonical name and alias", async function (assert) {+ extraConnectorComponent(+ "canonical-outlet",+ <template>+ <span class="canonical">Canonical</span>+ </template>+ );+ extraConnectorComponent(+ "alias-outlet",+ <template>+ <span class="alias">Alias</span>+ </template>+ );++ await render(+ <template>+ <PluginOutlet+ @name="canonical-outlet"+ @aliases={{array "alias-outlet"}}+ />+ </template>+ );++ assert.dom(".canonical").hasText("Canonical");+ assert.dom(".alias").hasText("Alias");+ });++ test("deprecated alias emits warning when connectors exist", async function (assert) {+ extraConnectorComponent(+ "old-name",+ <template>+ <span class="old">Old</span>+ </template>+ );++ await render(+ <template>+ <PluginOutlet+ @name="new-name"+ @aliases={{array+ (hash name="old-name" deprecated=true since="4.0")+ }}+ />+ </template>+ );++ assert.dom(".old").hasText("Old");+ assert.true(+ this.consoleWarnStub.calledWithMatch(+ /Plugin outlet "old-name" has been renamed to "new-name"/+ )+ );+ });++ test("deprecated alias does not emit warning when no connectors exist", async function (assert) {+ await render(+ <template>+ <PluginOutlet+ @name="new-name"+ @aliases={{array+ (hash name="old-name" deprecated=true since="4.0")+ }}+ />+ </template>+ );++ assert.false(+ this.consoleWarnStub.calledWithMatch(/old-name/),+ "no deprecation warning emitted"+ );+ });++ test("deprecated alias uses custom message when provided", async function (assert) {+ extraConnectorComponent(+ "legacy-name",+ <template>+ <span class="legacy">Legacy</span>+ </template>+ );++ await render(+ <template>+ <PluginOutlet+ @name="modern-name"+ @aliases={{array+ (hash+ name="legacy-name"+ deprecated=true+ since="4.0"+ message="Use modern-name instead of legacy-name"+ )+ }}+ />+ </template>+ );++ assert.dom(".legacy").hasText("Legacy");+ assert.true(+ this.consoleWarnStub.calledWithMatch(+ /Use modern-name instead of legacy-name/+ )+ );+ });++ test("non-deprecated alias does not emit warnings", async function (assert) {+ extraConnectorComponent(+ "alternate-name",+ <template>+ <span class="alt">Alt</span>+ </template>+ );++ await render(+ <template>+ <PluginOutlet+ @name="primary-name"+ @aliases={{array "alternate-name"}}+ />+ </template>+ );++ assert.dom(".alt").hasText("Alt");+ assert.strictEqual(+ this.consoleWarnStub.callCount,+ 0,+ "no warnings emitted"+ );+ });++ test("wrapper outlet aliases resolve __before and __after connectors", async function (assert) {+ extraConnectorComponent(+ "old-wrapper__before",+ <template>+ <span class="alias-before">Before from alias</span>+ </template>+ );+ extraConnectorComponent(+ "old-wrapper__after",+ <template>+ <span class="alias-after">After from alias</span>+ </template>+ );++ await render(+ <template>+ <PluginOutlet @name="new-wrapper" @aliases={{array "old-wrapper"}}>+ <span class="wrapped">Wrapped content</span>+ </PluginOutlet>+ </template>+ );++ assert.dom(".alias-before").hasText("Before from alias");+ assert.dom(".wrapped").hasText("Wrapped content");+ assert.dom(".alias-after").hasText("After from alias");+ });++ test("@deprecated emits warning when connectors exist", async function (assert) {+ extraConnectorComponent(+ "doomed-outlet",+ <template>+ <span class="doomed">Doomed</span>+ </template>+ );++ await render(+ <template>+ <PluginOutlet+ @name="doomed-outlet"+ @deprecated={{hash since="4.0"}}+ />+ </template>+ );++ assert.dom(".doomed").hasText("Doomed");+ assert.true(+ this.consoleWarnStub.calledWithMatch(+ /Plugin outlet "doomed-outlet" is deprecated/+ )+ );+ });++ test("@deprecated does not emit warning when no connectors exist", async function (assert) {+ await render(+ <template>+ <PluginOutlet+ @name="doomed-outlet"+ @deprecated={{hash since="4.0"}}+ />+ </template>+ );++ assert.false(+ this.consoleWarnStub.calledWithMatch(/doomed-outlet/),+ "no deprecation warning emitted"+ );+ });++ test("@deprecated uses custom message", async function (assert) {+ extraConnectorComponent(+ "old-outlet",+ <template>+ <span class="old-outlet">Old</span>+ </template>+ );++ await render(+ <template>+ <PluginOutlet+ @name="old-outlet"+ @deprecated={{hash+ since="4.0"+ message="This outlet will be removed. Use the Block API."+ }}+ />+ </template>+ );++ assert.dom(".old-outlet").hasText("Old");+ assert.true(+ this.consoleWarnStub.calledWithMatch(+ /This outlet will be removed\. Use the Block API\./+ )+ );+ });++ test("multiple aliases on same outlet", async function (assert) {+ extraConnectorComponent(+ "alias-one",+ <template>+ <span class="one">One</span>+ </template>+ );+ extraConnectorComponent(+ "alias-two",+ <template>+ <span class="two">Two</span>+ </template>+ );++ await render(+ <template>+ <PluginOutlet+ @name="target-outlet"+ @aliases={{array "alias-one" "alias-two"}}+ />+ </template>+ );++ assert.dom(".one").hasText("One");+ assert.dom(".two").hasText("Two");+ });++ test("file-based connectors under alias name render in canonical outlet", async function (assert) {+ registerTemporaryModule(+ `${TEMPLATE_PREFIX}/old-file-outlet/my-connector`,+ hbs`<span class="file-alias">File-based alias connector</span>`+ );++ await render(+ <template>+ <PluginOutlet+ @name="new-file-outlet"+ @aliases={{array "old-file-outlet"}}+ />+ </template>+ );++ assert.dom(".file-alias").hasText("File-based alias connector");+ });++ test("connectorsExist returns true when connectors exist only under alias", async function (assert) {+ extraConnectorComponent(+ "only-alias-outlet",+ <template>+ <span class="only-alias">Only alias</span>+ </template>+ );++ await render(+ <template>+ <PluginOutlet+ @name="empty-canonical"+ @aliases={{array "only-alias-outlet"}}+ >+ <span class="default">Default content</span>+ </PluginOutlet>+ </template>+ );++ assert.dom(".only-alias").hasText("Only alias");+ assert.dom(".default").doesNotExist();+ });++ test("mixed deprecated and non-deprecated aliases", async function (assert) {+ extraConnectorComponent(+ "deprecated-alias",+ <template>+ <span class="dep">Deprecated</span>+ </template>+ );+ extraConnectorComponent(+ "active-alias",+ <template>+ <span class="active">Active</span>+ </template>+ );++ await render(+ <template>+ <PluginOutlet+ @name="main-outlet"+ @aliases={{array+ (hash name="deprecated-alias" deprecated=true since="4.0")+ "active-alias"+ }}+ />+ </template>+ );++ assert.dom(".dep").hasText("Deprecated");+ assert.dom(".active").hasText("Active");+ assert.true(+ this.consoleWarnStub.calledWithMatch(/deprecated-alias/),+ "deprecated alias emits warning"+ );+ assert.false(+ this.consoleWarnStub.calledWithMatch(/active-alias/),+ "non-deprecated alias does not emit warning"+ );+ });++ test("DEBUG assertion: alias with deprecation properties but no deprecated flag", function (assert) {+ assert.throws(+ () => {+ const aliases = [{ name: "bad-alias", since: "4.0" }];+ // Trigger normalization+ aliases.map(normalizeAlias);+ },+ /has deprecation properties.*but `deprecated` is not true/,+ "throws when alias has since without deprecated=true"+ );+ });++ test("DEBUG assertion: alias with invalid position value", function (assert) {+ assert.throws(+ () => normalizeAlias({ name: "bad-pos", position: "middle" }),+ /invalid position "middle"/,+ "throws for invalid position value"+ );+ });++ test("position='after' routes alias connectors to wrapper __after outlet", async function (assert) {+ extraConnectorComponent(+ "old-standalone-outlet",+ <template>+ <span class="from-old-standalone">Old standalone</span>+ </template>+ );++ await render(+ <template>+ <PluginOutlet+ @name="new-wrapper-outlet"+ @aliases={{array+ (hash+ name="old-standalone-outlet"+ position="after"+ deprecated=true+ since="4.0"+ )+ }}+ >+ <span class="wrapped">Wrapped content</span>+ </PluginOutlet>+ </template>+ );++ assert.dom(".wrapped").hasText("Wrapped content");+ assert.dom(".from-old-standalone").hasText("Old standalone");+ });++ test("position='before' routes alias connectors to wrapper __before outlet", async function (assert) {+ extraConnectorComponent(+ "old-above-outlet",+ <template>+ <span class="from-old-above">Old above</span>+ </template>+ );++ await render(+ <template>+ <PluginOutlet+ @name="new-wrapper-outlet"+ @aliases={{array (hash name="old-above-outlet" position="before")}}+ >+ <span class="wrapped">Wrapped content</span>+ </PluginOutlet>+ </template>+ );++ assert.dom(".wrapped").hasText("Wrapped content");+ assert.dom(".from-old-above").hasText("Old above");+ });++ test("position-targeted alias does not render in main outlet", async function (assert) {+ extraConnectorComponent(+ "targeted-alias",+ <template>+ <span class="targeted">Targeted</span>+ </template>+ );++ await render(+ <template>+ <PluginOutlet+ @name="standalone-outlet"+ @aliases={{array (hash name="targeted-alias" position="after")}}+ />+ </template>+ );++ assert.dom(".targeted").doesNotExist();+ });++ test("position-targeted alias with connectorTagName preserves wrapper element", async function (assert) {+ registerTemporaryModule(+ `${TEMPLATE_PREFIX}/old-tagged-outlet/my-connector`,+ hbs`<span class="legacy-content">Legacy connector</span>`+ );++ await render(+ <template>+ <PluginOutlet+ @name="new-wrapper-with-tag"+ @aliases={{array+ (hash+ name="old-tagged-outlet"+ position="after"+ connectorTagName="span"+ )+ }}+ >+ <span class="wrapped">Wrapped</span>+ </PluginOutlet>+ </template>+ );++ assert.dom(".wrapped").hasText("Wrapped");+ assert.dom(".legacy-content").hasText("Legacy connector");+ const wrapper = find(".legacy-content").parentElement;+ assert.strictEqual(+ wrapper.tagName,+ "SPAN",+ "legacy connector is wrapped in a <span> from connectorTagName"+ );+ });++ test("position-targeted alias without connectorTagName renders tagless", async function (assert) {+ registerTemporaryModule(+ `${TEMPLATE_PREFIX}/old-tagless-outlet/my-connector`,+ hbs`<span class="tagless-content">Tagless connector</span>`+ );++ await render(+ <template>+ <PluginOutlet+ @name="new-wrapper-tagless"+ @aliases={{array (hash name="old-tagless-outlet" position="after")}}+ >+ <span class="wrapped">Wrapped</span>+ </PluginOutlet>+ </template>+ );++ assert.dom(".wrapped").hasText("Wrapped");+ assert.dom(".tagless-content").hasText("Tagless connector");+ });++ test("position-targeted alias with deprecation emits warning", async function (assert) {+ extraConnectorComponent(+ "old-below-outlet",+ <template>+ <span class="old-below">Old below</span>+ </template>+ );++ await render(+ <template>+ <PluginOutlet+ @name="wrapper-outlet"+ @aliases={{array+ (hash+ name="old-below-outlet"+ position="after"+ deprecated=true+ since="4.0"+ )+ }}+ >+ <span class="wrapped">Content</span>+ </PluginOutlet>+ </template>+ );++ assert.dom(".old-below").hasText("Old below");+ assert.true(+ this.consoleWarnStub.calledWithMatch(/old-below-outlet/),+ "deprecated position alias emits warning"+ );+ });+ }+);