@atlaskit/mention 26.1.0 → 26.2.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # @atlaskit/mention
 
+## 26.2.0
+
+### Minor Changes
+
+- [`971e92e232624`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/971e92e232624) -
+  Added a new `DISABLED` visual variant for mention chips so rendering surfaces (such as the editor
+  mentions plugin) can render a chip in a non-interactive disabled state with an explanatory
+  tooltip. Includes optional `MentionProvider` hooks that let consumers drive the disabled state
+  reactively and observe mention deletions.
+
+  **`@atlaskit/mention`**
+  - New `MentionType.DISABLED` enum value and matching style on `PrimitiveMention`.
+  - New optional `isDisabled` and `disabledTooltip` props on the React `<Mention>` component. When
+    `isDisabled` is set the chip becomes non-clickable, exposes `aria-disabled="true"`, remains
+    keyboard-focusable (`tabindex="0"`), and — when `disabledTooltip` is also set — is wrapped in an
+    ADS `<Tooltip>` whose content is mirrored into `aria-label` for screen readers.
+  - New `MentionDisabledState` (`{ disabled: boolean; tooltip?: string }`) and
+    `MentionDisabledStateInput` (`{ id: string }`) types, re-exported from `@atlaskit/mention` and
+    `@atlaskit/mention/resource`.
+  - New optional `MentionResource` config option `getMentionDisabledState` (forwarded by
+    `ContextMentionResource`) that surfaces through three new optional methods on the
+    `MentionProvider` interface:
+    - `getMentionDisabledState?(mention)` — predicate the editor calls to determine whether a chip
+      should render disabled.
+    - `subscribeToDisabledStateChanges?(listener)` — lets the editor re-evaluate the predicate when
+      the consumer's inputs change.
+    - `notifyMentionDestroyed?(mention)` — lets the consumer observe chip removals (e.g. to update
+      its source of truth).
+
+    All three methods are optional so existing `MentionProvider` implementations continue to compile
+    and behave identically.
+
+  **`@atlaskit/editor-plugin-mentions` + `@atlaskit/editor-core`**
+  - The mention `NodeView` now reads `MentionProvider.getMentionDisabledState?.({ id })` on every
+    state update and re-evaluates whenever `subscribeToDisabledStateChanges` notifies. When the
+    predicate returns `{ disabled: true }` the chip gets a new `.mention-disabled` class,
+    `aria-disabled="true"`, and an ADS `<Tooltip>` (anchored to the chip via `portalProviderAPI`)
+    carrying the `tooltip` text. The chip remains keyboard-focusable.
+  - The mention `NodeView.destroy()` calls `notifyMentionDestroyed?.({ id })` on the subscribed
+    provider so consumers can react to chip removals without depending on the editor's `onChange`.
+  - Added a matching `.editor-mention-primitive.mention-disabled` style in `@atlaskit/editor-core`
+    so the new class renders correctly inside the editor content container.
+  - Providers that don't implement the new optional methods are entirely unaffected.
+
+  **`@atlassian/conversation-assistant`, `@atlassian/conversation-assistant-widget` (chat store)**
+  - New `addSelectedAgentId({ conversationId, agentId })` action — append-only, no-dedup push onto
+    the conversation's `selectedAgentIds` history. Each call adds exactly one entry; duplicates are
+    preserved so the history is a 1-to-1 log of every agent chip currently in the editor.
+  - New `removeSelectedAgentId({ conversationId, agentId })` action — removes the **rightmost**
+    occurrence of an id (preserving order of other entries) for use when a single agent chip is
+    deleted from the editor.
+  - `setSelectedAgentIds` retains its wholesale-replace semantics (unchanged externally).
+  - The picker callback in `chat-input-refresh` is now wired to `addSelectedAgentId`; chip-deletion
+    is wired to `removeSelectedAgentId`. The active agent is always `selectedAgentIds.at(-1)`.
+
+  **`@atlassian/conversation-assistant-chat-prompt-input`**
+  - `useChatMentionResource` accepts new options `getSelectedAgentIds`, `disabledAgentTooltip`, and
+    `onAgentMentionDestroyed` that wire the new `MentionProvider` capabilities described above.
+  - `withAgentSupport` extended with the same options, plus a `notifyMentionDestroyed`
+    implementation that forwards to the consumer when a known agent chip is destroyed (sourced from
+    the editor `NodeView` rather than from `onChange`, which is not reliably called on every chat
+    surface).
+  - `<RovoChatPromptInput>` exposes new optional `selectedAgentIds`, `disabledAgentTooltip`, and
+    `onAgentMentionDeleted` props for consumers that want to drive the disabled-agent chip state
+    from their own store.
+
+  **`@atlassian/conversation-assistant-store`**
+  - JSDoc on the `selectedAgentIds` conversation field updated to document the new append-only /
+    rightmost-remove semantics and the canonical read pattern (`.at(-1)` for the active agent). No
+    runtime or type-shape change.
+
 ## 26.1.0
 
 ### Minor Changes

package/dist/cjs/api/ContextMentionResource.js

@@ -42,6 +42,20 @@ var ContextMentionResource = exports.default = /*#__PURE__*/function () {
     (0, _defineProperty2.default)(this, "filter", this.callWithContextIds('filter', 1));
     (0, _defineProperty2.default)(this, "recordMentionSelection", this.callWithContextIds('recordMentionSelection', 1));
     (0, _defineProperty2.default)(this, "shouldHighlightMention", this.callDefault('shouldHighlightMention'));
+    (0, _defineProperty2.default)(this, "getMentionDisabledState", function (mention) {
+      var _this$mentionProvider3, _this$mentionProvider4;
+      return (_this$mentionProvider3 = (_this$mentionProvider4 = _this.mentionProvider).getMentionDisabledState) === null || _this$mentionProvider3 === void 0 ? void 0 : _this$mentionProvider3.call(_this$mentionProvider4, mention);
+    });
+    (0, _defineProperty2.default)(this, "subscribeToDisabledStateChanges", function (listener) {
+      var _this$mentionProvider5, _this$mentionProvider6, _this$mentionProvider7;
+      return (_this$mentionProvider5 = (_this$mentionProvider6 = (_this$mentionProvider7 = _this.mentionProvider).subscribeToDisabledStateChanges) === null || _this$mentionProvider6 === void 0 ? void 0 : _this$mentionProvider6.call(_this$mentionProvider7, listener)) !== null && _this$mentionProvider5 !== void 0 ? _this$mentionProvider5 : function () {
+        return undefined;
+      };
+    });
+    (0, _defineProperty2.default)(this, "notifyMentionDestroyed", function (mention) {
+      var _this$mentionProvider8, _this$mentionProvider9;
+      return (_this$mentionProvider8 = (_this$mentionProvider9 = _this.mentionProvider).notifyMentionDestroyed) === null || _this$mentionProvider8 === void 0 ? void 0 : _this$mentionProvider8.call(_this$mentionProvider9, mention);
+    });
     (0, _defineProperty2.default)(this, "isFiltering", this.callDefault('isFiltering'));
     this.mentionProvider = mentionProvider;
     this.contextIdentifier = contextIdentifier;

package/dist/cjs/api/MentionResource.js

@@ -210,6 +210,12 @@ var MentionResource = exports.MentionResource = /*#__PURE__*/function (_Abstract
       }
       return false;
     }
+  }, {
+    key: "getMentionDisabledState",
+    value: function getMentionDisabledState(mention) {
+      var _this$config$getMenti, _this$config;
+      return (_this$config$getMenti = (_this$config = this.config).getMentionDisabledState) === null || _this$config$getMenti === void 0 ? void 0 : _this$config$getMenti.call(_this$config, mention);
+    }
   }, {
     key: "notify",
     value: function notify(searchTime, mentionResult, query) {

package/dist/cjs/components/DisabledMentionTooltip/index.js

@@ -0,0 +1,20 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
+var _react = _interopRequireDefault(require("react"));
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != (0, _typeof2.default)(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
+var AsyncDisabledMentionTooltip = /*#__PURE__*/_react.default.lazy(function () {
+  return Promise.resolve().then(function () {
+    return _interopRequireWildcard(require( /* webpackChunkName: "@atlaskit-internal_@atlaskit/mention/disabled-mention-tooltip" */'./main'));
+  }).then(function (module) {
+    return {
+      default: module.DisabledMentionTooltip
+    };
+  });
+});
+var _default = exports.default = AsyncDisabledMentionTooltip;

package/dist/cjs/components/DisabledMentionTooltip/main.js

@@ -0,0 +1,24 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.DisabledMentionTooltip = void 0;
+var _tooltip = _interopRequireDefault(require("@atlaskit/tooltip"));
+var _react = _interopRequireDefault(require("react"));
+/**
+ * Wraps a disabled `<Mention>` chip with a tooltip explaining why the chip
+ * is disabled. The chip itself remains non-interactive; the tooltip is the
+ * sole hover affordance.
+ */
+var DisabledMentionTooltip = exports.DisabledMentionTooltip = function DisabledMentionTooltip(_ref) {
+  var tooltip = _ref.tooltip,
+    children = _ref.children;
+  return /*#__PURE__*/_react.default.createElement(_tooltip.default, {
+    content: tooltip,
+    position: "top"
+  }, function (triggerProps) {
+    return /*#__PURE__*/_react.default.createElement("span", triggerProps, children);
+  });
+};

package/dist/cjs/components/Mention/PrimitiveMention.js

@@ -20,7 +20,7 @@ var _excluded = ["mentionType"];
  * @jsx jsx
  */
 // eslint-disable-next-line @atlaskit/ui-styling-standard/use-compiled -- Ignored via go/DSP-18766
-var mentionStyle = (0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)({}, _types.MentionType.SELF, {
+var mentionStyle = (0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)({}, _types.MentionType.SELF, {
   background: "var(--ds-background-brand-bold, #1868DB)",
   borderColor: 'transparent',
   text: "var(--ds-text-inverse, #FFFFFF)",
@@ -38,6 +38,13 @@ var mentionStyle = (0, _defineProperty2.default)((0, _defineProperty2.default)((
   text: "var(--ds-text-subtle, #505258)",
   hoveredBackground: "var(--ds-background-neutral-hovered, #0B120E24)",
   pressedBackground: "var(--ds-background-neutral-pressed, #080F214A)"
+}), _types.MentionType.DISABLED, {
+  background: "var(--ds-background-disabled, #0515240F)",
+  borderColor: 'transparent',
+  text: "var(--ds-text-disabled, #080F214A)",
+  // Disabled chips do not change on hover / press.
+  hoveredBackground: "var(--ds-background-disabled, #0515240F)",
+  pressedBackground: "var(--ds-background-disabled, #0515240F)"
 });
 var getStyle = function getStyle(_ref, property) {
   var mentionType = _ref.mentionType;

package/dist/cjs/components/Mention/index.js

@@ -17,12 +17,15 @@ var _focusRing = _interopRequireDefault(require("@atlaskit/focus-ring"));
 var _MessagesIntlProvider = _interopRequireDefault(require("../MessagesIntlProvider"));
 var _PrimitiveMention = _interopRequireDefault(require("./PrimitiveMention"));
 var _NoAccessTooltip = _interopRequireDefault(require("../NoAccessTooltip"));
+var _DisabledMentionTooltip = _interopRequireDefault(require("../DisabledMentionTooltip"));
 var _types = require("../../types");
 var _analytics = require("../../util/analytics");
 var _withAnalyticsEvents = _interopRequireDefault(require("@atlaskit/analytics-next/withAnalyticsEvents"));
 var _ufo = require("@atlaskit/ufo");
 var _i18n = require("../../util/i18n");
 var _ufoExperiences = require("./ufoExperiences");
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 function _callSuper(t, o, e) { return o = (0, _getPrototypeOf2.default)(o), (0, _possibleConstructorReturn2.default)(t, _isNativeReflectConstruct() ? Reflect.construct(o, e || [], (0, _getPrototypeOf2.default)(t).constructor) : o.apply(t, e)); }
 function _isNativeReflectConstruct() { try { var t = !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {})); } catch (t) {} return (_isNativeReflectConstruct = function _isNativeReflectConstruct() { return !!t; })(); }
 var ANALYTICS_HOVER_DELAY = exports.ANALYTICS_HOVER_DELAY = 1000;
@@ -36,7 +39,12 @@ var MentionInternal = exports.MentionInternal = /*#__PURE__*/function (_React$Pu
       var _this$props = _this.props,
         id = _this$props.id,
         text = _this$props.text,
-        onClick = _this$props.onClick;
+        onClick = _this$props.onClick,
+        isDisabled = _this$props.isDisabled;
+      if (isDisabled) {
+        // Disabled chips do not invoke their click handler.
+        return;
+      }
       if (onClick) {
         onClick(id, text, e);
       }
@@ -72,7 +80,11 @@ var MentionInternal = exports.MentionInternal = /*#__PURE__*/function (_React$Pu
     (0, _defineProperty2.default)(_this, "getMentionType", function () {
       var _this$props4 = _this.props,
         accessLevel = _this$props4.accessLevel,
-        isHighlighted = _this$props4.isHighlighted;
+        isHighlighted = _this$props4.isHighlighted,
+        isDisabled = _this$props4.isDisabled;
+      if (isDisabled) {
+        return _types.MentionType.DISABLED;
+      }
       if (isHighlighted) {
         return _types.MentionType.SELF;
       }
@@ -122,11 +134,25 @@ var MentionInternal = exports.MentionInternal = /*#__PURE__*/function (_React$Pu
       var text = props.text,
         id = props.id,
         accessLevel = props.accessLevel,
-        localId = props.localId;
+        localId = props.localId,
+        disabledTooltip = props.disabledTooltip;
       var mentionType = this.getMentionType();
       var failedMention = text === "@".concat(UNKNOWN_USER_ID);
-      var showTooltip = mentionType === _types.MentionType.RESTRICTED;
-      var mentionComponent = /*#__PURE__*/_react.default.createElement(_focusRing.default, null, /*#__PURE__*/_react.default.createElement(_PrimitiveMention.default, {
+      var showRestrictedTooltip = mentionType === _types.MentionType.RESTRICTED;
+      var showDisabledTooltip = mentionType === _types.MentionType.DISABLED && !!disabledTooltip;
+
+      // A11y: when the chip is in the disabled visual state, expose
+      // `aria-disabled` so assistive tech announces it as such. The
+      // disabled-tooltip text is mirrored into `aria-label` so the
+      // announcement carries the reason even without portal-id wiring for
+      // `aria-describedby`.
+      var isDisabledChip = mentionType === _types.MentionType.DISABLED;
+      var disabledA11yProps = isDisabledChip ? _objectSpread({
+        'aria-disabled': true
+      }, disabledTooltip ? {
+        'aria-label': "".concat(text || '@...', " \u2014 ").concat(disabledTooltip)
+      } : {}) : {};
+      var mentionComponent = /*#__PURE__*/_react.default.createElement(_focusRing.default, null, /*#__PURE__*/_react.default.createElement(_PrimitiveMention.default, (0, _extends2.default)({
         mentionType: mentionType,
         onClick: handleOnClick,
         onMouseEnter: handleOnMouseEnter,
@@ -134,11 +160,28 @@ var MentionInternal = exports.MentionInternal = /*#__PURE__*/function (_React$Pu
         spellCheck: false,
         "data-testid": "mention-".concat(id),
         "data-mention-type": mentionType,
-        "data-mention-tooltip": showTooltip
-      }, failedMention ? this.renderUnknownUserError(id) : text || '@...'));
+        "data-mention-tooltip": showRestrictedTooltip || showDisabledTooltip
+      }, disabledA11yProps), failedMention ? this.renderUnknownUserError(id) : text || '@...'));
       var ssrPlaceholderProp = props.ssrPlaceholderId ? {
         'data-ssr-placeholder': props.ssrPlaceholderId
       } : {};
+      var wrappedMention = function () {
+        if (showRestrictedTooltip) {
+          return /*#__PURE__*/_react.default.createElement(_react.default.Suspense, {
+            fallback: mentionComponent
+          }, /*#__PURE__*/_react.default.createElement(_NoAccessTooltip.default, {
+            name: text
+          }, mentionComponent));
+        }
+        if (showDisabledTooltip) {
+          return /*#__PURE__*/_react.default.createElement(_react.default.Suspense, {
+            fallback: mentionComponent
+          }, /*#__PURE__*/_react.default.createElement(_DisabledMentionTooltip.default, {
+            tooltip: disabledTooltip
+          }, mentionComponent));
+        }
+        return mentionComponent;
+      }();
       return /*#__PURE__*/_react.default.createElement(_ufoExperiences.UfoErrorBoundary, {
         id: id
       }, /*#__PURE__*/_react.default.createElement("span", (0, _extends2.default)({
@@ -147,11 +190,7 @@ var MentionInternal = exports.MentionInternal = /*#__PURE__*/function (_React$Pu
         "data-local-id": localId,
         "data-access-level": accessLevel,
         spellCheck: false
-      }, ssrPlaceholderProp), /*#__PURE__*/_react.default.createElement(_MessagesIntlProvider.default, null, showTooltip ? /*#__PURE__*/_react.default.createElement(_react.default.Suspense, {
-        fallback: mentionComponent
-      }, /*#__PURE__*/_react.default.createElement(_NoAccessTooltip.default, {
-        name: text
-      }, mentionComponent)) : mentionComponent)));
+      }, ssrPlaceholderProp), /*#__PURE__*/_react.default.createElement(_MessagesIntlProvider.default, null, wrappedMention)));
     }
   }]);
 }(_react.default.PureComponent);

package/dist/cjs/types.js

@@ -17,11 +17,21 @@ exports.isTeamMention = isTeamMention;
  * Extends {@link ServiceConfig} which provides the base `url`, `securityProvider`,
  * and `refreshedSecurityProvider` fields.
  */
+/**
+ * Describes whether a mention should be rendered in its disabled visual
+ * state and what tooltip (if any) should be shown on hover.
+ */
+/**
+ * The minimal input shape used by `getMentionDisabledState`. Kept as a named
+ * type so the config callback and the provider method share the same input
+ * surface, and so callers do not have to fabricate fields they do not have.
+ */
 // data is returned from team search service
 var MentionType = exports.MentionType = /*#__PURE__*/function (MentionType) {
   MentionType[MentionType["SELF"] = 0] = "SELF";
   MentionType[MentionType["RESTRICTED"] = 1] = "RESTRICTED";
   MentionType[MentionType["DEFAULT"] = 2] = "DEFAULT";
+  MentionType[MentionType["DISABLED"] = 3] = "DISABLED";
   return MentionType;
 }({});
 var UserAccessLevel = exports.UserAccessLevel = /*#__PURE__*/function (UserAccessLevel) {

package/dist/cjs/util/analytics.js

@@ -12,7 +12,7 @@ var _types = require("../types");
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 var packageName = "@atlaskit/mention";
-var packageVersion = "26.0.4";
+var packageVersion = "26.1.0";
 var SLI_EVENT_TYPE = exports.SLI_EVENT_TYPE = 'sli';
 var SMART_EVENT_TYPE = exports.SMART_EVENT_TYPE = 'smart';
 var fireAnalyticsMentionTypeaheadEvent = exports.fireAnalyticsMentionTypeaheadEvent = function fireAnalyticsMentionTypeaheadEvent(props) {

package/dist/es2019/api/ContextMentionResource.js

@@ -20,6 +20,18 @@ export default class ContextMentionResource {
     _defineProperty(this, "filter", this.callWithContextIds('filter', 1));
     _defineProperty(this, "recordMentionSelection", this.callWithContextIds('recordMentionSelection', 1));
     _defineProperty(this, "shouldHighlightMention", this.callDefault('shouldHighlightMention'));
+    _defineProperty(this, "getMentionDisabledState", mention => {
+      var _this$mentionProvider, _this$mentionProvider2;
+      return (_this$mentionProvider = (_this$mentionProvider2 = this.mentionProvider).getMentionDisabledState) === null || _this$mentionProvider === void 0 ? void 0 : _this$mentionProvider.call(_this$mentionProvider2, mention);
+    });
+    _defineProperty(this, "subscribeToDisabledStateChanges", listener => {
+      var _this$mentionProvider3, _this$mentionProvider4, _this$mentionProvider5;
+      return (_this$mentionProvider3 = (_this$mentionProvider4 = (_this$mentionProvider5 = this.mentionProvider).subscribeToDisabledStateChanges) === null || _this$mentionProvider4 === void 0 ? void 0 : _this$mentionProvider4.call(_this$mentionProvider5, listener)) !== null && _this$mentionProvider3 !== void 0 ? _this$mentionProvider3 : () => undefined;
+    });
+    _defineProperty(this, "notifyMentionDestroyed", mention => {
+      var _this$mentionProvider6, _this$mentionProvider7;
+      return (_this$mentionProvider6 = (_this$mentionProvider7 = this.mentionProvider).notifyMentionDestroyed) === null || _this$mentionProvider6 === void 0 ? void 0 : _this$mentionProvider6.call(_this$mentionProvider7, mention);
+    });
     _defineProperty(this, "isFiltering", this.callDefault('isFiltering'));
     this.mentionProvider = mentionProvider;
     this.contextIdentifier = contextIdentifier;

package/dist/es2019/api/MentionResource.js

@@ -156,6 +156,10 @@ export class MentionResource extends AbstractMentionResource {
     }
     return false;
   }
+  getMentionDisabledState(mention) {
+    var _this$config$getMenti, _this$config;
+    return (_this$config$getMenti = (_this$config = this.config).getMentionDisabledState) === null || _this$config$getMenti === void 0 ? void 0 : _this$config$getMenti.call(_this$config, mention);
+  }
   notify(searchTime, mentionResult, query) {
     if (searchTime > this.lastReturnedSearch) {
       this.lastReturnedSearch = searchTime;

package/dist/es2019/components/DisabledMentionTooltip/index.js

@@ -0,0 +1,7 @@
+import React from 'react';
+const AsyncDisabledMentionTooltip = /*#__PURE__*/React.lazy(() => import( /* webpackChunkName: "@atlaskit-internal_@atlaskit/mention/disabled-mention-tooltip" */'./main').then(module => {
+  return {
+    default: module.DisabledMentionTooltip
+  };
+}));
+export default AsyncDisabledMentionTooltip;

package/dist/es2019/components/DisabledMentionTooltip/main.js

@@ -0,0 +1,14 @@
+import Tooltip from '@atlaskit/tooltip';
+import React from 'react';
+/**
+ * Wraps a disabled `<Mention>` chip with a tooltip explaining why the chip
+ * is disabled. The chip itself remains non-interactive; the tooltip is the
+ * sole hover affordance.
+ */
+export const DisabledMentionTooltip = ({
+  tooltip,
+  children
+}) => /*#__PURE__*/React.createElement(Tooltip, {
+  content: tooltip,
+  position: "top"
+}, triggerProps => /*#__PURE__*/React.createElement("span", triggerProps, children));

package/dist/es2019/components/Mention/PrimitiveMention.js

@@ -29,6 +29,14 @@ const mentionStyle = {
     text: "var(--ds-text-subtle, #505258)",
     hoveredBackground: "var(--ds-background-neutral-hovered, #0B120E24)",
     pressedBackground: "var(--ds-background-neutral-pressed, #080F214A)"
+  },
+  [MentionType.DISABLED]: {
+    background: "var(--ds-background-disabled, #0515240F)",
+    borderColor: 'transparent',
+    text: "var(--ds-text-disabled, #080F214A)",
+    // Disabled chips do not change on hover / press.
+    hoveredBackground: "var(--ds-background-disabled, #0515240F)",
+    pressedBackground: "var(--ds-background-disabled, #0515240F)"
   }
 };
 const getStyle = ({

package/dist/es2019/components/Mention/index.js

@@ -5,6 +5,7 @@ import FocusRing from '@atlaskit/focus-ring';
 import MessagesIntlProvider from '../MessagesIntlProvider';
 import PrimitiveMention from './PrimitiveMention';
 import AsyncNoAccessTooltip from '../NoAccessTooltip';
+import AsyncDisabledMentionTooltip from '../DisabledMentionTooltip';
 import { isRestricted, MentionType } from '../../types';
 import { fireAnalyticsMentionEvent } from '../../util/analytics';
 import withAnalyticsEvents from '@atlaskit/analytics-next/withAnalyticsEvents';
@@ -20,8 +21,13 @@ export class MentionInternal extends React.PureComponent {
       const {
         id,
         text,
-        onClick
+        onClick,
+        isDisabled
       } = this.props;
+      if (isDisabled) {
+        // Disabled chips do not invoke their click handler.
+        return;
+      }
       if (onClick) {
         onClick(id, text, e);
       }
@@ -59,8 +65,12 @@ export class MentionInternal extends React.PureComponent {
     _defineProperty(this, "getMentionType", () => {
       const {
         accessLevel,
-        isHighlighted
+        isHighlighted,
+        isDisabled
       } = this.props;
+      if (isDisabled) {
+        return MentionType.DISABLED;
+      }
       if (isHighlighted) {
         return MentionType.SELF;
       }
@@ -101,12 +111,27 @@ export class MentionInternal extends React.PureComponent {
       text,
       id,
       accessLevel,
-      localId
+      localId,
+      disabledTooltip
     } = props;
     const mentionType = this.getMentionType();
     const failedMention = text === `@${UNKNOWN_USER_ID}`;
-    const showTooltip = mentionType === MentionType.RESTRICTED;
-    const mentionComponent = /*#__PURE__*/React.createElement(FocusRing, null, /*#__PURE__*/React.createElement(PrimitiveMention, {
+    const showRestrictedTooltip = mentionType === MentionType.RESTRICTED;
+    const showDisabledTooltip = mentionType === MentionType.DISABLED && !!disabledTooltip;
+
+    // A11y: when the chip is in the disabled visual state, expose
+    // `aria-disabled` so assistive tech announces it as such. The
+    // disabled-tooltip text is mirrored into `aria-label` so the
+    // announcement carries the reason even without portal-id wiring for
+    // `aria-describedby`.
+    const isDisabledChip = mentionType === MentionType.DISABLED;
+    const disabledA11yProps = isDisabledChip ? {
+      'aria-disabled': true,
+      ...(disabledTooltip ? {
+        'aria-label': `${text || '@...'} — ${disabledTooltip}`
+      } : {})
+    } : {};
+    const mentionComponent = /*#__PURE__*/React.createElement(FocusRing, null, /*#__PURE__*/React.createElement(PrimitiveMention, _extends({
       mentionType: mentionType,
       onClick: handleOnClick,
       onMouseEnter: handleOnMouseEnter,
@@ -114,11 +139,28 @@ export class MentionInternal extends React.PureComponent {
       spellCheck: false,
       "data-testid": `mention-${id}`,
       "data-mention-type": mentionType,
-      "data-mention-tooltip": showTooltip
-    }, failedMention ? this.renderUnknownUserError(id) : text || '@...'));
+      "data-mention-tooltip": showRestrictedTooltip || showDisabledTooltip
+    }, disabledA11yProps), failedMention ? this.renderUnknownUserError(id) : text || '@...'));
     const ssrPlaceholderProp = props.ssrPlaceholderId ? {
       'data-ssr-placeholder': props.ssrPlaceholderId
     } : {};
+    const wrappedMention = (() => {
+      if (showRestrictedTooltip) {
+        return /*#__PURE__*/React.createElement(React.Suspense, {
+          fallback: mentionComponent
+        }, /*#__PURE__*/React.createElement(AsyncNoAccessTooltip, {
+          name: text
+        }, mentionComponent));
+      }
+      if (showDisabledTooltip) {
+        return /*#__PURE__*/React.createElement(React.Suspense, {
+          fallback: mentionComponent
+        }, /*#__PURE__*/React.createElement(AsyncDisabledMentionTooltip, {
+          tooltip: disabledTooltip
+        }, mentionComponent));
+      }
+      return mentionComponent;
+    })();
     return /*#__PURE__*/React.createElement(UfoErrorBoundary, {
       id: id
     }, /*#__PURE__*/React.createElement("span", _extends({
@@ -127,11 +169,7 @@ export class MentionInternal extends React.PureComponent {
       "data-local-id": localId,
       "data-access-level": accessLevel,
       spellCheck: false
-    }, ssrPlaceholderProp), /*#__PURE__*/React.createElement(MessagesIntlProvider, null, showTooltip ? /*#__PURE__*/React.createElement(React.Suspense, {
-      fallback: mentionComponent
-    }, /*#__PURE__*/React.createElement(AsyncNoAccessTooltip, {
-      name: text
-    }, mentionComponent)) : mentionComponent)));
+    }, ssrPlaceholderProp), /*#__PURE__*/React.createElement(MessagesIntlProvider, null, wrappedMention)));
   }
 }
 const MentionWithAnalytics = withAnalyticsEvents({

package/dist/es2019/types.js

@@ -6,12 +6,24 @@
  * and `refreshedSecurityProvider` fields.
  */
 
+/**
+ * Describes whether a mention should be rendered in its disabled visual
+ * state and what tooltip (if any) should be shown on hover.
+ */
+
+/**
+ * The minimal input shape used by `getMentionDisabledState`. Kept as a named
+ * type so the config callback and the provider method share the same input
+ * surface, and so callers do not have to fabricate fields they do not have.
+ */
+
 // data is returned from team search service
 
 export let MentionType = /*#__PURE__*/function (MentionType) {
   MentionType[MentionType["SELF"] = 0] = "SELF";
   MentionType[MentionType["RESTRICTED"] = 1] = "RESTRICTED";
   MentionType[MentionType["DEFAULT"] = 2] = "DEFAULT";
+  MentionType[MentionType["DISABLED"] = 3] = "DISABLED";
   return MentionType;
 }({});
 export let UserAccessLevel = /*#__PURE__*/function (UserAccessLevel) {

package/dist/es2019/util/analytics.js

@@ -2,7 +2,7 @@ import { OPERATIONAL_EVENT_TYPE, UI_EVENT_TYPE } from '@atlaskit/analytics-gas-t
 import { ELEMENTS_CHANNEL } from '../_constants';
 import { ComponentNames, isSpecialMentionText } from '../types';
 const packageName = "@atlaskit/mention";
-const packageVersion = "26.0.4";
+const packageVersion = "26.1.0";
 export const SLI_EVENT_TYPE = 'sli';
 export const SMART_EVENT_TYPE = 'smart';
 export const fireAnalyticsMentionTypeaheadEvent = props => (action, duration, userIds = [], query) => {

package/dist/esm/api/ContextMentionResource.js

@@ -36,6 +36,20 @@ var ContextMentionResource = /*#__PURE__*/function () {
     _defineProperty(this, "filter", this.callWithContextIds('filter', 1));
     _defineProperty(this, "recordMentionSelection", this.callWithContextIds('recordMentionSelection', 1));
     _defineProperty(this, "shouldHighlightMention", this.callDefault('shouldHighlightMention'));
+    _defineProperty(this, "getMentionDisabledState", function (mention) {
+      var _this$mentionProvider3, _this$mentionProvider4;
+      return (_this$mentionProvider3 = (_this$mentionProvider4 = _this.mentionProvider).getMentionDisabledState) === null || _this$mentionProvider3 === void 0 ? void 0 : _this$mentionProvider3.call(_this$mentionProvider4, mention);
+    });
+    _defineProperty(this, "subscribeToDisabledStateChanges", function (listener) {
+      var _this$mentionProvider5, _this$mentionProvider6, _this$mentionProvider7;
+      return (_this$mentionProvider5 = (_this$mentionProvider6 = (_this$mentionProvider7 = _this.mentionProvider).subscribeToDisabledStateChanges) === null || _this$mentionProvider6 === void 0 ? void 0 : _this$mentionProvider6.call(_this$mentionProvider7, listener)) !== null && _this$mentionProvider5 !== void 0 ? _this$mentionProvider5 : function () {
+        return undefined;
+      };
+    });
+    _defineProperty(this, "notifyMentionDestroyed", function (mention) {
+      var _this$mentionProvider8, _this$mentionProvider9;
+      return (_this$mentionProvider8 = (_this$mentionProvider9 = _this.mentionProvider).notifyMentionDestroyed) === null || _this$mentionProvider8 === void 0 ? void 0 : _this$mentionProvider8.call(_this$mentionProvider9, mention);
+    });
     _defineProperty(this, "isFiltering", this.callDefault('isFiltering'));
     this.mentionProvider = mentionProvider;
     this.contextIdentifier = contextIdentifier;

package/dist/esm/api/MentionResource.js

@@ -203,6 +203,12 @@ export var MentionResource = /*#__PURE__*/function (_AbstractMentionResou) {
       }
       return false;
     }
+  }, {
+    key: "getMentionDisabledState",
+    value: function getMentionDisabledState(mention) {
+      var _this$config$getMenti, _this$config;
+      return (_this$config$getMenti = (_this$config = this.config).getMentionDisabledState) === null || _this$config$getMenti === void 0 ? void 0 : _this$config$getMenti.call(_this$config, mention);
+    }
   }, {
     key: "notify",
     value: function notify(searchTime, mentionResult, query) {

package/dist/esm/components/DisabledMentionTooltip/index.js

@@ -0,0 +1,9 @@
+import React from 'react';
+var AsyncDisabledMentionTooltip = /*#__PURE__*/React.lazy(function () {
+  return import( /* webpackChunkName: "@atlaskit-internal_@atlaskit/mention/disabled-mention-tooltip" */'./main').then(function (module) {
+    return {
+      default: module.DisabledMentionTooltip
+    };
+  });
+});
+export default AsyncDisabledMentionTooltip;

package/dist/esm/components/DisabledMentionTooltip/main.js

@@ -0,0 +1,17 @@
+import Tooltip from '@atlaskit/tooltip';
+import React from 'react';
+/**
+ * Wraps a disabled `<Mention>` chip with a tooltip explaining why the chip
+ * is disabled. The chip itself remains non-interactive; the tooltip is the
+ * sole hover affordance.
+ */
+export var DisabledMentionTooltip = function DisabledMentionTooltip(_ref) {
+  var tooltip = _ref.tooltip,
+    children = _ref.children;
+  return /*#__PURE__*/React.createElement(Tooltip, {
+    content: tooltip,
+    position: "top"
+  }, function (triggerProps) {
+    return /*#__PURE__*/React.createElement("span", triggerProps, children);
+  });
+};

package/dist/esm/components/Mention/PrimitiveMention.js

@@ -13,7 +13,7 @@ var _excluded = ["mentionType"];
 import { jsx, css } from '@emotion/react';
 import { MentionType } from '../../types';
 import { forwardRef } from 'react';
-var mentionStyle = _defineProperty(_defineProperty(_defineProperty({}, MentionType.SELF, {
+var mentionStyle = _defineProperty(_defineProperty(_defineProperty(_defineProperty({}, MentionType.SELF, {
   background: "var(--ds-background-brand-bold, #1868DB)",
   borderColor: 'transparent',
   text: "var(--ds-text-inverse, #FFFFFF)",
@@ -31,6 +31,13 @@ var mentionStyle = _defineProperty(_defineProperty(_defineProperty({}, MentionTy
   text: "var(--ds-text-subtle, #505258)",
   hoveredBackground: "var(--ds-background-neutral-hovered, #0B120E24)",
   pressedBackground: "var(--ds-background-neutral-pressed, #080F214A)"
+}), MentionType.DISABLED, {
+  background: "var(--ds-background-disabled, #0515240F)",
+  borderColor: 'transparent',
+  text: "var(--ds-text-disabled, #080F214A)",
+  // Disabled chips do not change on hover / press.
+  hoveredBackground: "var(--ds-background-disabled, #0515240F)",
+  pressedBackground: "var(--ds-background-disabled, #0515240F)"
 });
 var getStyle = function getStyle(_ref, property) {
   var mentionType = _ref.mentionType;

package/dist/esm/components/Mention/index.js

@@ -5,6 +5,8 @@ import _possibleConstructorReturn from "@babel/runtime/helpers/possibleConstruct
 import _getPrototypeOf from "@babel/runtime/helpers/getPrototypeOf";
 import _inherits from "@babel/runtime/helpers/inherits";
 import _defineProperty from "@babel/runtime/helpers/defineProperty";
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 function _callSuper(t, o, e) { return o = _getPrototypeOf(o), _possibleConstructorReturn(t, _isNativeReflectConstruct() ? Reflect.construct(o, e || [], _getPrototypeOf(t).constructor) : o.apply(t, e)); }
 function _isNativeReflectConstruct() { try { var t = !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {})); } catch (t) {} return (_isNativeReflectConstruct = function _isNativeReflectConstruct() { return !!t; })(); }
 import React from 'react';
@@ -12,6 +14,7 @@ import FocusRing from '@atlaskit/focus-ring';
 import MessagesIntlProvider from '../MessagesIntlProvider';
 import PrimitiveMention from './PrimitiveMention';
 import AsyncNoAccessTooltip from '../NoAccessTooltip';
+import AsyncDisabledMentionTooltip from '../DisabledMentionTooltip';
 import { isRestricted, MentionType } from '../../types';
 import { fireAnalyticsMentionEvent } from '../../util/analytics';
 import withAnalyticsEvents from '@atlaskit/analytics-next/withAnalyticsEvents';
@@ -29,7 +32,12 @@ export var MentionInternal = /*#__PURE__*/function (_React$PureComponent) {
       var _this$props = _this.props,
         id = _this$props.id,
         text = _this$props.text,
-        onClick = _this$props.onClick;
+        onClick = _this$props.onClick,
+        isDisabled = _this$props.isDisabled;
+      if (isDisabled) {
+        // Disabled chips do not invoke their click handler.
+        return;
+      }
       if (onClick) {
         onClick(id, text, e);
       }
@@ -65,7 +73,11 @@ export var MentionInternal = /*#__PURE__*/function (_React$PureComponent) {
     _defineProperty(_this, "getMentionType", function () {
       var _this$props4 = _this.props,
         accessLevel = _this$props4.accessLevel,
-        isHighlighted = _this$props4.isHighlighted;
+        isHighlighted = _this$props4.isHighlighted,
+        isDisabled = _this$props4.isDisabled;
+      if (isDisabled) {
+        return MentionType.DISABLED;
+      }
       if (isHighlighted) {
         return MentionType.SELF;
       }
@@ -115,11 +127,25 @@ export var MentionInternal = /*#__PURE__*/function (_React$PureComponent) {
       var text = props.text,
         id = props.id,
         accessLevel = props.accessLevel,
-        localId = props.localId;
+        localId = props.localId,
+        disabledTooltip = props.disabledTooltip;
       var mentionType = this.getMentionType();
       var failedMention = text === "@".concat(UNKNOWN_USER_ID);
-      var showTooltip = mentionType === MentionType.RESTRICTED;
-      var mentionComponent = /*#__PURE__*/React.createElement(FocusRing, null, /*#__PURE__*/React.createElement(PrimitiveMention, {
+      var showRestrictedTooltip = mentionType === MentionType.RESTRICTED;
+      var showDisabledTooltip = mentionType === MentionType.DISABLED && !!disabledTooltip;
+
+      // A11y: when the chip is in the disabled visual state, expose
+      // `aria-disabled` so assistive tech announces it as such. The
+      // disabled-tooltip text is mirrored into `aria-label` so the
+      // announcement carries the reason even without portal-id wiring for
+      // `aria-describedby`.
+      var isDisabledChip = mentionType === MentionType.DISABLED;
+      var disabledA11yProps = isDisabledChip ? _objectSpread({
+        'aria-disabled': true
+      }, disabledTooltip ? {
+        'aria-label': "".concat(text || '@...', " \u2014 ").concat(disabledTooltip)
+      } : {}) : {};
+      var mentionComponent = /*#__PURE__*/React.createElement(FocusRing, null, /*#__PURE__*/React.createElement(PrimitiveMention, _extends({
         mentionType: mentionType,
         onClick: handleOnClick,
         onMouseEnter: handleOnMouseEnter,
@@ -127,11 +153,28 @@ export var MentionInternal = /*#__PURE__*/function (_React$PureComponent) {
         spellCheck: false,
         "data-testid": "mention-".concat(id),
         "data-mention-type": mentionType,
-        "data-mention-tooltip": showTooltip
-      }, failedMention ? this.renderUnknownUserError(id) : text || '@...'));
+        "data-mention-tooltip": showRestrictedTooltip || showDisabledTooltip
+      }, disabledA11yProps), failedMention ? this.renderUnknownUserError(id) : text || '@...'));
       var ssrPlaceholderProp = props.ssrPlaceholderId ? {
         'data-ssr-placeholder': props.ssrPlaceholderId
       } : {};
+      var wrappedMention = function () {
+        if (showRestrictedTooltip) {
+          return /*#__PURE__*/React.createElement(React.Suspense, {
+            fallback: mentionComponent
+          }, /*#__PURE__*/React.createElement(AsyncNoAccessTooltip, {
+            name: text
+          }, mentionComponent));
+        }
+        if (showDisabledTooltip) {
+          return /*#__PURE__*/React.createElement(React.Suspense, {
+            fallback: mentionComponent
+          }, /*#__PURE__*/React.createElement(AsyncDisabledMentionTooltip, {
+            tooltip: disabledTooltip
+          }, mentionComponent));
+        }
+        return mentionComponent;
+      }();
       return /*#__PURE__*/React.createElement(UfoErrorBoundary, {
         id: id
       }, /*#__PURE__*/React.createElement("span", _extends({
@@ -140,11 +183,7 @@ export var MentionInternal = /*#__PURE__*/function (_React$PureComponent) {
         "data-local-id": localId,
         "data-access-level": accessLevel,
         spellCheck: false
-      }, ssrPlaceholderProp), /*#__PURE__*/React.createElement(MessagesIntlProvider, null, showTooltip ? /*#__PURE__*/React.createElement(React.Suspense, {
-        fallback: mentionComponent
-      }, /*#__PURE__*/React.createElement(AsyncNoAccessTooltip, {
-        name: text
-      }, mentionComponent)) : mentionComponent)));
+      }, ssrPlaceholderProp), /*#__PURE__*/React.createElement(MessagesIntlProvider, null, wrappedMention)));
     }
   }]);
 }(React.PureComponent);

package/dist/esm/types.js

@@ -6,12 +6,24 @@
  * and `refreshedSecurityProvider` fields.
  */
 
+/**
+ * Describes whether a mention should be rendered in its disabled visual
+ * state and what tooltip (if any) should be shown on hover.
+ */
+
+/**
+ * The minimal input shape used by `getMentionDisabledState`. Kept as a named
+ * type so the config callback and the provider method share the same input
+ * surface, and so callers do not have to fabricate fields they do not have.
+ */
+
 // data is returned from team search service
 
 export var MentionType = /*#__PURE__*/function (MentionType) {
   MentionType[MentionType["SELF"] = 0] = "SELF";
   MentionType[MentionType["RESTRICTED"] = 1] = "RESTRICTED";
   MentionType[MentionType["DEFAULT"] = 2] = "DEFAULT";
+  MentionType[MentionType["DISABLED"] = 3] = "DISABLED";
   return MentionType;
 }({});
 export var UserAccessLevel = /*#__PURE__*/function (UserAccessLevel) {

package/dist/esm/util/analytics.js

@@ -5,7 +5,7 @@ import { OPERATIONAL_EVENT_TYPE, UI_EVENT_TYPE } from '@atlaskit/analytics-gas-t
 import { ELEMENTS_CHANNEL } from '../_constants';
 import { ComponentNames, isSpecialMentionText } from '../types';
 var packageName = "@atlaskit/mention";
-var packageVersion = "26.0.4";
+var packageVersion = "26.1.0";
 export var SLI_EVENT_TYPE = 'sli';
 export var SMART_EVENT_TYPE = 'smart';
 export var fireAnalyticsMentionTypeaheadEvent = function fireAnalyticsMentionTypeaheadEvent(props) {

package/dist/types/api/ContextMentionResource.d.ts

@@ -1,5 +1,5 @@
 import { type MentionProvider, type MentionContextIdentifier, ErrorCallback, InfoCallback, ResultCallback } from './MentionResource';
-import { type MentionDescription, type InviteFromMentionProvider, type XProductInviteMentionProvider, type AnalyticsCallback } from '../types';
+import { type MentionDescription, type MentionDisabledState, type MentionDisabledStateInput, type InviteFromMentionProvider, type XProductInviteMentionProvider, type AnalyticsCallback } from '../types';
 export type { MentionDescription };
 export type MentionProviderFunctions = Omit<{
     [Key in keyof MentionProvider]: MentionProvider[Key] extends Function ? MentionProvider[Key] : never;
@@ -19,5 +19,10 @@ export default class ContextMentionResource implements MentionProvider {
     filter: (query?: string, contextIdentifier?: MentionContextIdentifier) => void;
     recordMentionSelection: (mention: MentionDescription, contextIdentifier?: MentionContextIdentifier) => void;
     shouldHighlightMention: (mention: MentionDescription) => boolean;
+    getMentionDisabledState: (mention: MentionDisabledStateInput) => MentionDisabledState | undefined;
+    subscribeToDisabledStateChanges: (listener: () => void) => (() => void);
+    notifyMentionDestroyed: (mention: {
+        id: string;
+    }) => void;
     isFiltering: (query: string) => boolean;
 }

package/dist/types/api/MentionResource.d.ts

@@ -1,4 +1,4 @@
-import { type AnalyticsCallback, type ErrorCallback, type InfoCallback, type InviteFlow, type MentionContextIdentifier, type MentionDescription, type MentionNameDetails, type MentionProvider, type MentionResourceConfig, type MentionsResult, type MentionStats, type ResourceProvider, type ResultCallback, type UserRole } from '../types';
+import { type AnalyticsCallback, type ErrorCallback, type InfoCallback, type InviteFlow, type MentionContextIdentifier, type MentionDescription, type MentionDisabledState, type MentionDisabledStateInput, type MentionNameDetails, type MentionProvider, type MentionResourceConfig, type MentionsResult, type MentionStats, type ResourceProvider, type ResultCallback, type UserRole } from '../types';
 export type { MentionStats, ResultCallback, ErrorCallback, InfoCallback, MentionResourceConfig, ResourceProvider, MentionContextIdentifier, MentionProvider, } from '../types';
 /**
  * Configuration for the TeamMentionResource, which extends {@link MentionResourceConfig}
@@ -62,6 +62,7 @@ export declare class MentionResource extends AbstractMentionResource implements
     inviteXProductUser?: (userId: string, mentionName: string) => Promise<void>;
     constructor(config: MentionResourceConfig);
     shouldHighlightMention(mention: MentionDescription): boolean;
+    getMentionDisabledState(mention: MentionDisabledStateInput): MentionDisabledState | undefined;
     notify(searchTime: number, mentionResult: MentionsResult, query?: string): void;
     notifyError(error: Error, query?: string): void;
     filter(query?: string, contextIdentifier?: MentionContextIdentifier): Promise<void>;

package/dist/types/components/DisabledMentionTooltip/index.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+declare const AsyncDisabledMentionTooltip: React.LazyExoticComponent<({ tooltip, children }: {
+    children: React.ReactNode;
+    tooltip: string;
+}) => React.JSX.Element>;
+export default AsyncDisabledMentionTooltip;

package/dist/types/components/DisabledMentionTooltip/main.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+type Props = {
+    children: React.ReactNode;
+    tooltip: string;
+};
+/**
+ * Wraps a disabled `<Mention>` chip with a tooltip explaining why the chip
+ * is disabled. The chip itself remains non-interactive; the tooltip is the
+ * sole hover affordance.
+ */
+export declare const DisabledMentionTooltip: ({ tooltip, children }: Props) => React.JSX.Element;
+export {};

package/dist/types/components/Mention/index.d.ts

@@ -5,7 +5,19 @@ export declare const ANALYTICS_HOVER_DELAY = 1000;
 export declare const UNKNOWN_USER_ID = "_|unknown|_";
 export type OwnProps = {
     accessLevel?: string;
+    /**
+     * Tooltip text shown on hover when the chip is disabled. Ignored when
+     * `isDisabled` is false. When omitted, no tooltip is rendered even if
+     * `isDisabled` is true.
+     */
+    disabledTooltip?: string;
     id: string;
+    /**
+     * When true, the mention chip is rendered in its disabled visual state
+     * (`MentionType.DISABLED`) and click handlers are not invoked. Takes
+     * precedence over `isHighlighted` and the restricted state.
+     */
+    isDisabled?: boolean;
     isHighlighted?: boolean;
     localId?: string;
     onClick?: MentionEventHandler;

package/dist/types/types.d.ts

@@ -39,6 +39,24 @@ export interface MentionResourceConfig extends ServiceConfig {
      * calls to `filter` will be debounced to reduce the number of network requests.
      */
     debounceTime?: number;
+    /**
+     * A function to determine whether a given mention should be rendered in
+     * its disabled visual state (`MentionType.DISABLED`), and what tooltip
+     * (if any) to display when the disabled chip is hovered.
+     *
+     * Returning `{ disabled: false }` (or `undefined`) leaves the mention in
+     * whatever state the other predicates resolve to.
+     *
+     * The input deliberately exposes only the mention's `id` because the
+     * canonical caller (the editor mentions `NodeView`) does not have the
+     * full `MentionDescription` in scope. Implementations should look the
+     * additional context they need (e.g. agent metadata) up via the `id`.
+     *
+     * @param mention - The minimal mention identifier to evaluate.
+     * @returns `{ disabled, tooltip? }` describing the disabled visual state,
+     * or `undefined` to leave it unchanged.
+     */
+    getMentionDisabledState?: (mention: MentionDisabledStateInput) => MentionDisabledState | undefined;
     /**
      * Custom HTTP headers to include in mention service requests.
      */
@@ -94,6 +112,22 @@ export interface MentionResourceConfig extends ServiceConfig {
      */
     userRole?: UserRole;
 }
+/**
+ * Describes whether a mention should be rendered in its disabled visual
+ * state and what tooltip (if any) should be shown on hover.
+ */
+export interface MentionDisabledState {
+    disabled: boolean;
+    tooltip?: string;
+}
+/**
+ * The minimal input shape used by `getMentionDisabledState`. Kept as a named
+ * type so the config callback and the provider method share the same input
+ * surface, and so callers do not have to fabricate fields they do not have.
+ */
+export interface MentionDisabledStateInput {
+    id: string;
+}
 export interface ResourceProvider<Result> {
     /**
      * Subscribe to ResourceProvider results
@@ -119,9 +153,40 @@ export type MentionContextIdentifier = {
 };
 export interface MentionProvider extends ResourceProvider<MentionDescription[]>, InviteFromMentionProvider, XProductInviteMentionProvider {
     filter(query?: string, contextIdentifier?: MentionContextIdentifier): void;
+    /**
+     * Optional. When implemented, lets the rendering surface ask whether a
+     * mention should be displayed in its disabled visual state, and what
+     * tooltip to surface on hover. Returning `undefined` (or omitting the
+     * method entirely) is equivalent to "not disabled".
+     */
+    getMentionDisabledState?(mention: MentionDisabledStateInput): MentionDisabledState | undefined;
     isFiltering(query: string): boolean;
+    /**
+     * Optional. Called by the rendering surface (e.g. the editor NodeView)
+     * when a mention chip is destroyed (removed from the doc). This is the
+     * lowest-level deletion signal — it fires regardless of how the chip was
+     * removed (backspace, select-and-delete, programmatic replace, …) and
+     * does not depend on the editor's debounced `onChange` callback.
+     *
+     * Implementations typically forward the call to consumers via the chat
+     * layer so they can react (e.g. update `selectedAgentIds`).
+     */
+    notifyMentionDestroyed?(mention: {
+        id: string;
+    }): void;
     recordMentionSelection(mention: MentionDescription, contextIdentifier?: MentionContextIdentifier): void;
     shouldHighlightMention(mention: MentionDescription): boolean;
+    /**
+     * Optional. When implemented, lets the rendering surface subscribe to
+     * changes in the disabled-state predicate so already-rendered chips can
+     * re-evaluate themselves when the external state that drives
+     * `getMentionDisabledState` changes (e.g. the active agent selection in
+     * Rovo Chat). Implementations should invoke the listener after their
+     * own state changes.
+     *
+     * Returns an unsubscribe function. Callers MUST invoke it on teardown.
+     */
+    subscribeToDisabledStateChanges?(listener: () => void): () => void;
 }
 export interface HighlightDetail {
     end: number;
@@ -188,7 +253,8 @@ export interface OnMentionEvent {
 export declare enum MentionType {
     SELF = 0,
     RESTRICTED = 1,
-    DEFAULT = 2
+    DEFAULT = 2,
+    DISABLED = 3
 }
 export declare enum UserAccessLevel {
     NONE = 0,

package/dist/types-ts4.5/api/ContextMentionResource.d.ts

@@ -1,5 +1,5 @@
 import { type MentionProvider, type MentionContextIdentifier, ErrorCallback, InfoCallback, ResultCallback } from './MentionResource';
-import { type MentionDescription, type InviteFromMentionProvider, type XProductInviteMentionProvider, type AnalyticsCallback } from '../types';
+import { type MentionDescription, type MentionDisabledState, type MentionDisabledStateInput, type InviteFromMentionProvider, type XProductInviteMentionProvider, type AnalyticsCallback } from '../types';
 export type { MentionDescription };
 export type MentionProviderFunctions = Omit<{
     [Key in keyof MentionProvider]: MentionProvider[Key] extends Function ? MentionProvider[Key] : never;
@@ -19,5 +19,10 @@ export default class ContextMentionResource implements MentionProvider {
     filter: (query?: string, contextIdentifier?: MentionContextIdentifier) => void;
     recordMentionSelection: (mention: MentionDescription, contextIdentifier?: MentionContextIdentifier) => void;
     shouldHighlightMention: (mention: MentionDescription) => boolean;
+    getMentionDisabledState: (mention: MentionDisabledStateInput) => MentionDisabledState | undefined;
+    subscribeToDisabledStateChanges: (listener: () => void) => (() => void);
+    notifyMentionDestroyed: (mention: {
+        id: string;
+    }) => void;
     isFiltering: (query: string) => boolean;
 }

package/dist/types-ts4.5/api/MentionResource.d.ts

@@ -1,4 +1,4 @@
-import { type AnalyticsCallback, type ErrorCallback, type InfoCallback, type InviteFlow, type MentionContextIdentifier, type MentionDescription, type MentionNameDetails, type MentionProvider, type MentionResourceConfig, type MentionsResult, type MentionStats, type ResourceProvider, type ResultCallback, type UserRole } from '../types';
+import { type AnalyticsCallback, type ErrorCallback, type InfoCallback, type InviteFlow, type MentionContextIdentifier, type MentionDescription, type MentionDisabledState, type MentionDisabledStateInput, type MentionNameDetails, type MentionProvider, type MentionResourceConfig, type MentionsResult, type MentionStats, type ResourceProvider, type ResultCallback, type UserRole } from '../types';
 export type { MentionStats, ResultCallback, ErrorCallback, InfoCallback, MentionResourceConfig, ResourceProvider, MentionContextIdentifier, MentionProvider, } from '../types';
 /**
  * Configuration for the TeamMentionResource, which extends {@link MentionResourceConfig}
@@ -62,6 +62,7 @@ export declare class MentionResource extends AbstractMentionResource implements
     inviteXProductUser?: (userId: string, mentionName: string) => Promise<void>;
     constructor(config: MentionResourceConfig);
     shouldHighlightMention(mention: MentionDescription): boolean;
+    getMentionDisabledState(mention: MentionDisabledStateInput): MentionDisabledState | undefined;
     notify(searchTime: number, mentionResult: MentionsResult, query?: string): void;
     notifyError(error: Error, query?: string): void;
     filter(query?: string, contextIdentifier?: MentionContextIdentifier): Promise<void>;

package/dist/types-ts4.5/components/DisabledMentionTooltip/index.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+declare const AsyncDisabledMentionTooltip: React.LazyExoticComponent<({ tooltip, children }: {
+    children: React.ReactNode;
+    tooltip: string;
+}) => React.JSX.Element>;
+export default AsyncDisabledMentionTooltip;

package/dist/types-ts4.5/components/DisabledMentionTooltip/main.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+type Props = {
+    children: React.ReactNode;
+    tooltip: string;
+};
+/**
+ * Wraps a disabled `<Mention>` chip with a tooltip explaining why the chip
+ * is disabled. The chip itself remains non-interactive; the tooltip is the
+ * sole hover affordance.
+ */
+export declare const DisabledMentionTooltip: ({ tooltip, children }: Props) => React.JSX.Element;
+export {};

package/dist/types-ts4.5/components/Mention/index.d.ts

@@ -5,7 +5,19 @@ export declare const ANALYTICS_HOVER_DELAY = 1000;
 export declare const UNKNOWN_USER_ID = "_|unknown|_";
 export type OwnProps = {
     accessLevel?: string;
+    /**
+     * Tooltip text shown on hover when the chip is disabled. Ignored when
+     * `isDisabled` is false. When omitted, no tooltip is rendered even if
+     * `isDisabled` is true.
+     */
+    disabledTooltip?: string;
     id: string;
+    /**
+     * When true, the mention chip is rendered in its disabled visual state
+     * (`MentionType.DISABLED`) and click handlers are not invoked. Takes
+     * precedence over `isHighlighted` and the restricted state.
+     */
+    isDisabled?: boolean;
     isHighlighted?: boolean;
     localId?: string;
     onClick?: MentionEventHandler;

package/dist/types-ts4.5/types.d.ts

@@ -39,6 +39,24 @@ export interface MentionResourceConfig extends ServiceConfig {
      * calls to `filter` will be debounced to reduce the number of network requests.
      */
     debounceTime?: number;
+    /**
+     * A function to determine whether a given mention should be rendered in
+     * its disabled visual state (`MentionType.DISABLED`), and what tooltip
+     * (if any) to display when the disabled chip is hovered.
+     *
+     * Returning `{ disabled: false }` (or `undefined`) leaves the mention in
+     * whatever state the other predicates resolve to.
+     *
+     * The input deliberately exposes only the mention's `id` because the
+     * canonical caller (the editor mentions `NodeView`) does not have the
+     * full `MentionDescription` in scope. Implementations should look the
+     * additional context they need (e.g. agent metadata) up via the `id`.
+     *
+     * @param mention - The minimal mention identifier to evaluate.
+     * @returns `{ disabled, tooltip? }` describing the disabled visual state,
+     * or `undefined` to leave it unchanged.
+     */
+    getMentionDisabledState?: (mention: MentionDisabledStateInput) => MentionDisabledState | undefined;
     /**
      * Custom HTTP headers to include in mention service requests.
      */
@@ -94,6 +112,22 @@ export interface MentionResourceConfig extends ServiceConfig {
      */
     userRole?: UserRole;
 }
+/**
+ * Describes whether a mention should be rendered in its disabled visual
+ * state and what tooltip (if any) should be shown on hover.
+ */
+export interface MentionDisabledState {
+    disabled: boolean;
+    tooltip?: string;
+}
+/**
+ * The minimal input shape used by `getMentionDisabledState`. Kept as a named
+ * type so the config callback and the provider method share the same input
+ * surface, and so callers do not have to fabricate fields they do not have.
+ */
+export interface MentionDisabledStateInput {
+    id: string;
+}
 export interface ResourceProvider<Result> {
     /**
      * Subscribe to ResourceProvider results
@@ -119,9 +153,40 @@ export type MentionContextIdentifier = {
 };
 export interface MentionProvider extends ResourceProvider<MentionDescription[]>, InviteFromMentionProvider, XProductInviteMentionProvider {
     filter(query?: string, contextIdentifier?: MentionContextIdentifier): void;
+    /**
+     * Optional. When implemented, lets the rendering surface ask whether a
+     * mention should be displayed in its disabled visual state, and what
+     * tooltip to surface on hover. Returning `undefined` (or omitting the
+     * method entirely) is equivalent to "not disabled".
+     */
+    getMentionDisabledState?(mention: MentionDisabledStateInput): MentionDisabledState | undefined;
     isFiltering(query: string): boolean;
+    /**
+     * Optional. Called by the rendering surface (e.g. the editor NodeView)
+     * when a mention chip is destroyed (removed from the doc). This is the
+     * lowest-level deletion signal — it fires regardless of how the chip was
+     * removed (backspace, select-and-delete, programmatic replace, …) and
+     * does not depend on the editor's debounced `onChange` callback.
+     *
+     * Implementations typically forward the call to consumers via the chat
+     * layer so they can react (e.g. update `selectedAgentIds`).
+     */
+    notifyMentionDestroyed?(mention: {
+        id: string;
+    }): void;
     recordMentionSelection(mention: MentionDescription, contextIdentifier?: MentionContextIdentifier): void;
     shouldHighlightMention(mention: MentionDescription): boolean;
+    /**
+     * Optional. When implemented, lets the rendering surface subscribe to
+     * changes in the disabled-state predicate so already-rendered chips can
+     * re-evaluate themselves when the external state that drives
+     * `getMentionDisabledState` changes (e.g. the active agent selection in
+     * Rovo Chat). Implementations should invoke the listener after their
+     * own state changes.
+     *
+     * Returns an unsubscribe function. Callers MUST invoke it on teardown.
+     */
+    subscribeToDisabledStateChanges?(listener: () => void): () => void;
 }
 export interface HighlightDetail {
     end: number;
@@ -188,7 +253,8 @@ export interface OnMentionEvent {
 export declare enum MentionType {
     SELF = 0,
     RESTRICTED = 1,
-    DEFAULT = 2
+    DEFAULT = 2,
+    DISABLED = 3
 }
 export declare enum UserAccessLevel {
     NONE = 0,

package/docs/0-intro.tsx

@@ -79,6 +79,27 @@ const _default_1: any = md`
 		/>
 	)}
 
+  ## Mention chip variants
+
+  The \`<Mention>\` chip has four visual variants:
+
+  - **Default** — a neutral chip rendered for any in-scope mention.
+  - **Self** — emphasised brand-coloured chip rendered when \`isHighlighted\`
+    is set, typically used to highlight a mention of the current user.
+  - **Restricted** — outlined chip rendered when the mention's
+    \`accessLevel\` indicates the referenced user does not have access; on
+    hover the chip surfaces a "no access" tooltip.
+  - **Disabled** — muted grey chip rendered when \`isDisabled\` is set.
+    Click handlers are suppressed, the chip exposes
+    \`aria-disabled="true"\`, and (with a \`disabledTooltip\` set) hover or
+    keyboard focus surfaces an ADS tooltip explaining why the chip is
+    disabled. The disabled chip remains keyboard-focusable so screen-reader
+    users encounter it and hear the reason.
+
+  Inside the editor, the disabled state is driven by
+  \`MentionProvider.getMentionDisabledState({ id })\` so rendering surfaces
+  don't need to thread per-chip props through ProseMirror node views.
+
   ${(<Props props={MentionProps} />)}
 
 `;

package/package.json

@@ -120,5 +120,5 @@
 			]
 		}
 	},
-	"version": "26.1.0"
+	"version": "26.2.0"
 }