@atlaskit/mention
Version:
A React component used to display user profiles in a list for 'Mention' functionality
954 lines (864 loc) • 23 kB
Markdown
<!-- API Report Version: 2.3 -->
## API Report File for "@atlaskit/mention"
> Do not edit this file. This report is auto-generated using
> [API Extractor](https://api-extractor.com/).
> [Learn more about API reports](https://hello.atlassian.net/wiki/spaces/UR/pages/1825484529/Package+API+Reports)
### Table of contents
- [Main Entry Types](#main-entry-types)
- [Peer Dependencies](#peer-dependencies)
### Main Entry Types
<!--SECTION START: Main Entry Types-->
```ts
import { IntlShape } from 'react-intl-next';
import { default as React_2 } from 'react';
import { ServiceConfig } from '@atlaskit/util-service-support/types';
import { SyntheticEvent } from 'react';
import { WithAnalyticsEventsProps } from '@atlaskit/analytics-next';
import { WithAnalyticsEventsProps as WithAnalyticsEventsProps_2 } from '@atlaskit/analytics-next/withAnalyticsEvents';
import { WithIntlProps } from 'react-intl-next';
// @public (undocumented)
export class AbstractMentionResource
extends AbstractResource<MentionDescription[]>
implements MentionProvider
{
// (undocumented)
filter(query?: string): void;
// (undocumented)
isFiltering(_query: string): boolean;
// (undocumented)
protected _notifyAllResultsListeners(mentionsResult: MentionsResult): void;
// (undocumented)
protected _notifyAnalyticsListeners(
event: string,
actionSubject: string,
action: string,
attributes?: {
[key: string]: any;
},
): void;
// (undocumented)
protected _notifyErrorListeners(error: Error, query?: string): void;
// (undocumented)
protected _notifyInfoListeners(info: string): void;
// (undocumented)
protected _notifyListeners(mentionsResult: MentionsResult, stats?: MentionStats): void;
// (undocumented)
recordMentionSelection(_mention: MentionDescription): void;
// (undocumented)
shouldHighlightMention(_mention: MentionDescription): boolean;
}
// @public (undocumented)
export class AbstractPresenceResource
extends AbstractResource<PresenceMap>
implements PresenceProvider
{
// (undocumented)
protected notifyListeners(presences: PresenceMap): void;
// (undocumented)
refreshPresence(userIds: string[]): void;
}
// @public (undocumented)
class AbstractResource<Result> implements ResourceProvider<Result> {
constructor();
// (undocumented)
protected allResultsListeners: Map<string, ResultCallback<Result>>;
// (undocumented)
protected analyticsListeners: Map<string, AnalyticsCallback>;
// (undocumented)
protected changeListeners: Map<string, ResultCallback<Result>>;
// (undocumented)
protected errListeners: Map<string, ErrorCallback_2>;
// (undocumented)
protected infoListeners: Map<string, InfoCallback>;
// (undocumented)
subscribe(
key: string,
callback?: ResultCallback<Result>,
errCallback?: ErrorCallback_2,
infoCallback?: InfoCallback,
allResultsCallback?: ResultCallback<Result>,
analyticsListeners?: AnalyticsCallback,
): void;
// (undocumented)
unsubscribe(key: string): void;
}
// @public (undocumented)
interface AnalyticsCallback {
// (undocumented)
(
event: string,
actionSubject: string,
action: string,
attributes?: {
[key: string]: any;
},
): void;
}
// @public
export class ContextMentionResource implements MentionProvider {
constructor(mentionProvider: MentionProvider, contextIdentifier: MentionContextIdentifier);
// (undocumented)
callDefault: <
K extends
| 'filter'
| 'isFiltering'
| 'recordMentionSelection'
| 'shouldHighlightMention'
| 'subscribe'
| 'unsubscribe',
>(
f: K,
) => MentionProvider[K];
// (undocumented)
callWithContextIds: <
K extends
| 'filter'
| 'isFiltering'
| 'recordMentionSelection'
| 'shouldHighlightMention'
| 'subscribe'
| 'unsubscribe',
>(
f: K,
declaredArgs: number,
) => MentionProvider[K];
// (undocumented)
filter: (
query?: string | undefined,
contextIdentifier?: MentionContextIdentifier | undefined,
) => void;
// (undocumented)
getContextIdentifier(): MentionContextIdentifier | undefined;
// (undocumented)
isFiltering: (query: string) => boolean;
// (undocumented)
recordMentionSelection: (
mention: MentionDescription,
contextIdentifier?: MentionContextIdentifier | undefined,
) => void;
// (undocumented)
shouldHighlightMention: (mention: MentionDescription) => boolean;
// (undocumented)
subscribe: (
key: string,
callback?: ResultCallback<MentionDescription[]> | undefined,
errCallback?: ErrorCallback_2 | undefined,
infoCallback?: InfoCallback | undefined,
allResultsCallback?: ResultCallback<MentionDescription[]> | undefined,
analyticsCallback?: AnalyticsCallback | undefined,
) => void;
// (undocumented)
unsubscribe: (key: string) => void;
}
// @public (undocumented)
interface Data {
// (undocumented)
PresenceBulk: PresenceBulk[];
}
// @public (undocumented)
export class DefaultMentionNameResolver implements MentionNameResolver {
constructor(client: MentionNameClient, analyticsProps?: WithAnalyticsEventsProps);
// (undocumented)
cacheName(id: string, name: string): void;
// (undocumented)
lookupName(id: string): MentionNameDetails | Promise<MentionNameDetails>;
// (undocumented)
static waitForBatch: number;
}
// @public (undocumented)
export const ELEMENTS_CHANNEL = 'fabric-elements';
// @public (undocumented)
interface ErrorCallback_2 {
// (undocumented)
(error: Error, query?: string): void;
}
// @public (undocumented)
interface Highlight {
// (undocumented)
mentionName: HighlightDetail[];
// (undocumented)
name: HighlightDetail[];
// (undocumented)
nickname: HighlightDetail[];
}
// @public (undocumented)
interface HighlightDetail {
// (undocumented)
end: number;
// (undocumented)
start: number;
}
// @public (undocumented)
interface InfoCallback {
// (undocumented)
(info: string): void;
}
// @public (undocumented)
export type InviteFlow = 'assign' | 'mention';
// @public (undocumented)
interface InviteFromMentionProvider {
// (undocumented)
onInviteItemClick?(flow: InviteFlow): void;
// (undocumented)
productName?: string;
// (undocumented)
shouldEnableInvite?: boolean;
// (undocumented)
userRole?: UserRole;
}
// @public (undocumented)
export const isResolvingMentionProvider: (p: any) => p is ResolvingMentionProvider;
// @public (undocumented)
export function isSpecialMention(mention: MentionDescription): boolean;
// @public (undocumented)
type LozengeColor = 'default' | 'inprogress' | 'moved' | 'new' | 'removed' | 'success';
// @public (undocumented)
interface LozengeProps {
// (undocumented)
appearance?: LozengeColor;
// (undocumented)
text: React.ReactNode;
}
// @public (undocumented)
export const Mention: React_2.ForwardRefExoticComponent<
Omit<Props_5, keyof WithAnalyticsEventsProps_2> & React_2.RefAttributes<any>
>;
// @public (undocumented)
export type Mention = MentionInternal;
// @public (undocumented)
export type MentionContextIdentifier = {
containerId?: string;
objectId?: string;
childObjectId?: string;
sessionId?: string;
};
// @public (undocumented)
interface MentionDescContext {
// (undocumented)
includesYou: boolean;
// (undocumented)
memberCount: number;
// (undocumented)
members: TeamMember[];
// (undocumented)
teamLink: string;
}
// @public (undocumented)
export interface MentionDescription {
// (undocumented)
accessLevel?: string;
// (undocumented)
avatarUrl?: string;
// (undocumented)
context?: MentionDescContext;
// (undocumented)
highlight?: Highlight;
// (undocumented)
id: string;
// (undocumented)
inContext?: boolean;
// (undocumented)
lozenge?: LozengeProps | string;
// (undocumented)
mentionName?: string;
// (undocumented)
name?: string;
// (undocumented)
nickname?: string;
// (undocumented)
presence?: Presence;
// (undocumented)
source?: string;
// (undocumented)
userType?: string;
}
// @public (undocumented)
type MentionEventHandler = (
mentionId: string,
text: string,
event?: SyntheticEvent<HTMLSpanElement>,
) => void;
// @public (undocumented)
class MentionInternal extends React_2.PureComponent<Props_5, {}> {
constructor(props: Props_5);
// (undocumented)
componentDidMount(): void;
// (undocumented)
componentWillUnmount(): void;
// (undocumented)
render(): JSX.Element;
// (undocumented)
renderUnknownUserError(id: string): JSX.Element;
}
// @public (undocumented)
export class MentionItem extends React_2.PureComponent<Props, {}> {
// (undocumented)
render(): JSX.Element;
}
// @public (undocumented)
export class MentionList extends React_2.PureComponent<Props_2, State> {
constructor(props: Props_2);
// (undocumented)
chooseCurrentSelection: () => void;
// (undocumented)
componentDidUpdate(): void;
// (undocumented)
mentionsCount: () => number;
// (undocumented)
render(): JSX.Element;
// (undocumented)
selectId: (id: string, callback?: () => any) => void;
// (undocumented)
selectIndex: (index: number, callback?: () => any) => void;
// (undocumented)
selectNext: () => void;
// (undocumented)
selectPrevious: () => void;
// (undocumented)
UNSAFE_componentWillReceiveProps(nextProps: Props_2): void;
}
// @public (undocumented)
export interface MentionNameClient {
// (undocumented)
getLookupLimit(): number;
// (undocumented)
lookupMentionNames(ids: string[]): Promise<MentionNameDetails[]>;
}
// @public (undocumented)
export interface MentionNameDetails {
// (undocumented)
id: string;
// (undocumented)
name?: string;
// (undocumented)
status: MentionNameStatus;
}
// @public (undocumented)
export interface MentionNameResolver {
// (undocumented)
cacheName(id: string, name: string): void;
// (undocumented)
lookupName(id: string): MentionNameDetails | Promise<MentionNameDetails>;
}
// @public (undocumented)
export enum MentionNameStatus {
// (undocumented)
OK = 2,
// (undocumented)
SERVICE_ERROR = 1,
// (undocumented)
UNKNOWN = 0,
}
// @public
class MentionPicker_2 extends React_2.PureComponent<
Props_4 &
WithAnalyticsEventsProps_2 & {
intl: IntlShape;
},
State_3
> {
constructor(
props: Props_4 &
WithAnalyticsEventsProps_2 & {
intl: IntlShape;
},
);
// (undocumented)
chooseCurrentSelection: () => void;
// (undocumented)
componentDidMount(): void;
// (undocumented)
componentWillUnmount(): void;
// (undocumented)
static defaultProps: {
onSelection: () => void;
onOpen: () => void;
onClose: () => void;
};
// (undocumented)
mentionsCount: () => number;
// (undocumented)
render(): JSX.Element;
// (undocumented)
selectId: (id: string, callback?: () => any) => void;
// (undocumented)
selectIndex: (index: number, callback?: () => any) => void;
// (undocumented)
selectNext: () => void;
// (undocumented)
selectPrevious: () => void;
// (undocumented)
UNSAFE_componentWillReceiveProps(nextProps: Props_4 & WithAnalyticsEventsProps_2): void;
}
// @public (undocumented)
const MentionPickerWithAnalytics: React_2.ForwardRefExoticComponent<
Omit<
Pick<
WithIntlProps<
React_2.PropsWithChildren<
Props_4 &
WithAnalyticsEventsProps_2 & {
intl: IntlShape;
}
>
>,
'children' | 'createAnalyticsEvent' | 'forwardedRef' | keyof Props_4
> &
React_2.RefAttributes<any>,
keyof WithAnalyticsEventsProps_2
> &
React_2.RefAttributes<any>
>;
// @public (undocumented)
type MentionPickerWithAnalytics = MentionPicker_2;
export { MentionPickerWithAnalytics as MentionPicker };
export default MentionPickerWithAnalytics;
// @public (undocumented)
export interface MentionProvider
extends ResourceProvider<MentionDescription[]>,
InviteFromMentionProvider {
// (undocumented)
filter(query?: string, contextIdentifier?: MentionContextIdentifier): void;
// (undocumented)
isFiltering(query: string): boolean;
// (undocumented)
recordMentionSelection(
mention: MentionDescription,
contextIdentifier?: MentionContextIdentifier,
): void;
// (undocumented)
shouldHighlightMention(mention: MentionDescription): boolean;
}
// @public
export class MentionResource extends AbstractMentionResource implements ResolvingMentionProvider {
constructor(config: MentionResourceConfig);
// (undocumented)
cacheMentionName(id: string, mentionName: string): void;
// (undocumented)
filter(query?: string, contextIdentifier?: MentionContextIdentifier): Promise<void>;
// (undocumented)
isFiltering(query: string): boolean;
// (undocumented)
notify(searchTime: number, mentionResult: MentionsResult, query?: string): void;
// (undocumented)
notifyError(error: Error, query?: string): void;
// (undocumented)
onInviteItemClick?: (flow: InviteFlow) => void;
// (undocumented)
productName?: string;
// (undocumented)
recordMentionSelection(
mention: MentionDescription,
contextIdentifier?: MentionContextIdentifier,
): Promise<void>;
// (undocumented)
recordSelection(
mention: MentionDescription,
contextIdentifier?: MentionContextIdentifier,
): Promise<void>;
protected remoteInitialState(
contextIdentifier?: MentionContextIdentifier,
): Promise<MentionsResult>;
// (undocumented)
protected remoteSearch(
query: string,
contextIdentifier?: MentionContextIdentifier,
): Promise<MentionsResult>;
// (undocumented)
resolveMentionName(id: string): MentionNameDetails | Promise<MentionNameDetails>;
// (undocumented)
shouldEnableInvite: boolean;
// (undocumented)
shouldHighlightMention(mention: MentionDescription): boolean;
// (undocumented)
supportsMentionNameResolving(): boolean;
// (undocumented)
protected updateActiveSearches(query: string): void;
// (undocumented)
userRole: UserRole;
// (undocumented)
protected verifyMentionConfig(config: MentionResourceConfig): void;
}
// @public (undocumented)
export interface MentionResourceConfig extends ServiceConfig {
// (undocumented)
containerId?: string;
// (undocumented)
debounceTime?: number;
// (undocumented)
mentionNameResolver?: MentionNameResolver;
// (undocumented)
onInviteItemClick?: (flow: InviteFlow) => void;
// (undocumented)
productId?: string;
// (undocumented)
productName?: string;
// (undocumented)
shouldEnableInvite?: boolean;
// (undocumented)
shouldHighlightMention?: (mention: MentionDescription) => boolean;
// (undocumented)
userRole?: UserRole;
}
// @public (undocumented)
export interface MentionsResult {
// (undocumented)
mentions: MentionDescription[];
// (undocumented)
query: string;
}
// @public (undocumented)
export type MentionStats = {
[key: string]: any;
};
// @public (undocumented)
interface OnClose {
// (undocumented)
(): void;
}
// @public (undocumented)
interface OnMentionEvent {
// (undocumented)
(mention: MentionDescription, event?: SyntheticEvent<any>): void;
}
// @public (undocumented)
interface OnOpen {
// (undocumented)
(): void;
}
// @public (undocumented)
type OwnProps = {
id: string;
text: string;
isHighlighted?: boolean;
accessLevel?: string;
onClick?: MentionEventHandler;
onMouseEnter?: MentionEventHandler;
onMouseLeave?: MentionEventHandler;
onHover?: () => void;
};
// @public (undocumented)
type Position = 'above' | 'auto' | 'below';
// @public (undocumented)
interface Presence {
// (undocumented)
status?: string;
// (undocumented)
time?: string;
}
// @public (undocumented)
interface PresenceBulk {
// (undocumented)
date: null | string;
// (undocumented)
message: null | string;
// (undocumented)
state: null | string;
// (undocumented)
stateMetadata?: string;
// (undocumented)
type: null | string;
// (undocumented)
userId: string;
}
// @public (undocumented)
interface PresenceCache {
// (undocumented)
contains(userId: string): boolean;
// (undocumented)
get(userId: string): Presence;
// (undocumented)
getBulk(userIds: string[]): PresenceMap;
// (undocumented)
getMissingUserIds(userIds: string[]): string[];
// (undocumented)
update(presUpdate: PresenceMap): void;
}
// @public (undocumented)
interface PresenceMap {
// (undocumented)
[userId: string]: Presence;
}
// @public (undocumented)
interface PresenceParser {
// (undocumented)
mapState(state: string): string;
// (undocumented)
parse(response: PresenceResponse): PresenceMap;
}
// @public (undocumented)
export interface PresenceProvider extends ResourceProvider<PresenceMap> {
// (undocumented)
refreshPresence(userIds: string[]): void;
}
// @public (undocumented)
export class PresenceResource extends AbstractPresenceResource {
constructor(config: PresenceResourceConfig);
// (undocumented)
refreshPresence(userIds: string[]): void;
}
// @public (undocumented)
interface PresenceResourceConfig {
// (undocumented)
cache?: PresenceCache;
// (undocumented)
cacheExpiry?: number;
// (undocumented)
cloudId: string;
// (undocumented)
parser?: PresenceParser;
// (undocumented)
productId?: string;
// (undocumented)
url: string;
}
// @public (undocumented)
interface PresenceResponse {
// (undocumented)
data: Data;
}
// @public (undocumented)
interface Props {
// (undocumented)
mention: MentionDescription;
// (undocumented)
onMouseEnter?: OnMentionEvent;
// (undocumented)
onMouseMove?: OnMentionEvent;
// (undocumented)
onSelection?: OnMentionEvent;
// (undocumented)
selected?: boolean;
}
// @public (undocumented)
interface Props_2 {
// (undocumented)
initialHighlightElement?: React_2.ReactElement | null;
// (undocumented)
mentions: MentionDescription[];
// (undocumented)
onSelection?: OnMentionEvent;
// (undocumented)
resourceError?: Error;
}
// @public (undocumented)
interface Props_3 {
// (undocumented)
onSelection?: OnMentionEvent;
// (undocumented)
presenceProvider?: PresenceProvider;
// (undocumented)
query?: string;
// (undocumented)
resourceError?: Error;
// (undocumented)
resourceProvider: MentionProvider;
}
// @public (undocumented)
interface Props_4 {
// (undocumented)
offsetX?: number;
// (undocumented)
offsetY?: number;
// (undocumented)
onClose?: OnClose;
// (undocumented)
onOpen?: OnOpen;
// (undocumented)
onSelection?: OnMentionEvent;
// (undocumented)
position?: Position;
// (undocumented)
presenceProvider?: PresenceProvider;
// (undocumented)
query?: string;
// (undocumented)
resourceProvider: MentionProvider;
// (undocumented)
target?: string;
// (undocumented)
zIndex?: number | string;
}
// @public (undocumented)
type Props_5 = OwnProps & WithAnalyticsEventsProps_2;
// @public (undocumented)
interface Props_6 {
// (undocumented)
accessLevel?: string;
// (undocumented)
id: string;
// (undocumented)
mentionProvider?: Promise<MentionProvider>;
// (undocumented)
onClick?: MentionEventHandler;
// (undocumented)
onMouseEnter?: MentionEventHandler;
// (undocumented)
onMouseLeave?: MentionEventHandler;
// (undocumented)
text: string;
}
// @public
export interface ResolvingMentionProvider extends MentionProvider {
// (undocumented)
cacheMentionName(id: string, mentionName: string): void;
// (undocumented)
resolveMentionName(id: string): MentionNameDetails | Promise<MentionNameDetails>;
// (undocumented)
supportsMentionNameResolving(): boolean;
}
// @public (undocumented)
export class ResourcedMention extends React_2.PureComponent<Props_6, State_4> {
constructor(props: Props_6);
// (undocumented)
componentDidMount(): void;
// (undocumented)
componentWillUnmount(): void;
// (undocumented)
_isMounted: boolean;
// (undocumented)
render(): JSX.Element;
// (undocumented)
UNSAFE_componentWillReceiveProps(nextProps: Props_6): void;
}
// @public (undocumented)
export const ResourcedMentionList: React_2.ForwardRefExoticComponent<
Omit<Props_3 & WithAnalyticsEventsProps, keyof WithAnalyticsEventsProps> &
React_2.RefAttributes<any>
>;
// @public (undocumented)
export type ResourcedMentionList = ResourcedMentionListWithoutAnalytics;
// @public (undocumented)
class ResourcedMentionListWithoutAnalytics extends React_2.PureComponent<
Props_3 & WithAnalyticsEventsProps,
State_2
> {
constructor(props: Props_3 & WithAnalyticsEventsProps);
// (undocumented)
chooseCurrentSelection: () => void;
// (undocumented)
componentDidMount(): void;
// (undocumented)
componentWillUnmount(): void;
// (undocumented)
mentionsCount: () => number;
// (undocumented)
render(): JSX.Element;
// (undocumented)
selectId: (id: string, callback?: () => any) => void;
// (undocumented)
selectIndex: (index: number, callback?: () => any) => void;
// (undocumented)
selectNext: () => void;
// (undocumented)
selectPrevious: () => void;
// (undocumented)
UNSAFE_componentWillReceiveProps(nextProps: Props_3): void;
}
// @public (undocumented)
interface ResourceProvider<Result> {
subscribe(
key: string,
callback?: ResultCallback<Result>,
errCallback?: ErrorCallback_2,
infoCallback?: InfoCallback,
allResultsCallback?: ResultCallback<Result>,
analyticsCallback?: AnalyticsCallback,
): void;
unsubscribe(key: string): void;
}
// @public (undocumented)
interface ResultCallback<T> {
// (undocumented)
(result: T, query?: string, stats?: MentionStats): void;
}
// @public (undocumented)
interface State {
// (undocumented)
selectedIndex: number;
// (undocumented)
selectedKey?: string;
}
// @public (undocumented)
interface State_2 {
// (undocumented)
mentions: MentionDescription[];
// (undocumented)
resourceError?: Error;
}
// @public (undocumented)
interface State_3 {
// (undocumented)
info?: string;
// (undocumented)
visible: boolean;
}
// @public (undocumented)
interface State_4 {
// (undocumented)
isHighlighted: boolean;
// (undocumented)
resolvedMentionName?: string;
}
// @public (undocumented)
export interface TeamMember {
// (undocumented)
id: string;
// (undocumented)
name: string;
}
// @public
export class TeamMentionResource extends MentionResource implements MentionProvider {
constructor(
userMentionConfig: MentionResourceConfig,
teamMentionConfig: TeamMentionResourceConfig,
);
// (undocumented)
filter(query?: string, contextIdentifier?: MentionContextIdentifier): Promise<void>;
// (undocumented)
notify(searchTime: number, mentionResult: MentionsResult, query?: string): void;
}
// @public (undocumented)
export interface TeamMentionResourceConfig extends MentionResourceConfig {
// (undocumented)
teamLinkResolver?: (teamId: string) => string;
}
// @public (undocumented)
export enum UserAccessLevel {
// (undocumented)
APPLICATION = 2,
// (undocumented)
CONTAINER = 3,
// (undocumented)
NONE = 0,
// (undocumented)
SITE = 1,
}
// @public (undocumented)
export type UserRole = 'admin' | 'basic' | 'trusted';
// @public (undocumented)
export enum UserType {
// (undocumented)
APP = 2,
// (undocumented)
DEFAULT = 0,
// (undocumented)
SPECIAL = 1,
// (undocumented)
SYSTEM = 4,
// (undocumented)
TEAM = 3,
}
// (No @packageDocumentation comment for this package)
```
<!--SECTION END: Main Entry Types-->
### Peer Dependencies
<!--SECTION START: Peer Dependencies-->
```json
{
"react": "^16.8.0",
"react-dom": "^16.8.0",
"react-intl-next": "npm:react-intl@^5.18.1"
}
```
<!--SECTION END: Peer Dependencies-->