@atlaskit/link-picker 1.6.0 → 1.7.1

package/dist/esm/ui/link-picker/index.js

@@ -7,25 +7,31 @@ function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (O
 function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = null != arguments[i] ? arguments[i] : {}; i % 2 ? ownKeys(Object(source), !0).forEach(function (key) { _defineProperty(target, key, source[key]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)) : ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } return target; }
 
 /** @jsx jsx */
-import { useCallback, useLayoutEffect, useReducer } from 'react';
+import { Fragment, useCallback, useLayoutEffect, useReducer } from 'react';
 import { jsx } from '@emotion/react';
 import { useIntl, FormattedMessage } from 'react-intl-next';
+import { useAnalyticsEvents } from '@atlaskit/analytics-next';
 import Button, { ButtonGroup } from '@atlaskit/button';
 import { FormFooter } from '@atlaskit/form';
 import EditorSearchIcon from '@atlaskit/icon/glyph/editor/search';
 import Tabs, { Tab, TabList } from '@atlaskit/tabs';
 import VisuallyHidden from '@atlaskit/visually-hidden';
+import createEventPayload from '../../analytics.codegen';
+import { ANALYTICS_CHANNEL } from '../../common/constants';
+import { usePlugins } from '../../services/use-plugins';
+import { useSearchQuery } from '../../services/use-search-query';
 import { messages } from './messages';
 import PanelTextInput from './text-input';
 import LinkSearchList from './link-search-list';
 import { normalizeUrl, isSafeUrl } from './url';
 import { rootContainerStyles, searchIconStyles, listTitleStyles, tabsWrapperStyles } from './styled';
 import { browser } from './browser';
-import { transformTimeStamp } from './transformTimeStamp';
 import Announcer from './announcer';
 import LinkSearchNoResults from './link-search-no-results';
-import { usePlugins } from '../../services/use-plugins';
+import { transformTimeStamp } from './transformTimeStamp';
+import LinkSearchError from './link-search-error';
 export var RECENT_SEARCH_LIST_SIZE = 5;
+export var CONTACT_SUPPORT_LINK = 'https://support.atlassian.com/contact/';
 export var testIds = {
   linkPicker: 'link-picker',
   urlInputField: 'link-url',
@@ -41,7 +47,8 @@ export var testIds = {
   searchResultLoadingIndicator: 'link-picker.results-loading-indicator',
   urlError: 'link-error',
   tabList: 'link-picker-tabs',
-  tabItem: 'link-picker-tab'
+  tabItem: 'link-picker-tab',
+  searchError: 'link-search-error'
 };
 var initState = {
   url: '',
@@ -64,6 +71,8 @@ function reducer(state, payload) {
 }
 
 function LinkPicker(_ref) {
+  var _queryState$query, _items$length, _errorFallback;
+
   var onSubmit = _ref.onSubmit,
       onCancel = _ref.onCancel,
       onContentResize = _ref.onContentResize,
@@ -71,6 +80,9 @@ function LinkPicker(_ref) {
       initUrl = _ref.url,
       initDisplayText = _ref.displayText;
 
+  var _useAnalyticsEvents = useAnalyticsEvents(),
+      createAnalyticsEvent = _useAnalyticsEvents.createAnalyticsEvent;
+
   var _useReducer = useReducer(reducer, _objectSpread(_objectSpread({}, initState), {}, {
     url: normalizeUrl(initUrl) || '',
     displayText: initDisplayText || ''
@@ -83,17 +95,23 @@ function LinkPicker(_ref) {
       selectedIndex = state.selectedIndex,
       url = state.url,
       displayText = state.displayText,
-      invalidUrl = state.invalidUrl;
-  var isEditing = !!initUrl;
+      invalidUrl = state.invalidUrl,
+      activeTab = state.activeTab;
   var intl = useIntl();
+  var queryState = useSearchQuery(state);
 
-  var _usePlugins = usePlugins(state, plugins),
+  var _usePlugins = usePlugins(queryState, activeTab, plugins),
       items = _usePlugins.items,
       isLoading = _usePlugins.isLoading,
-      isSelectedItem = _usePlugins.isSelectedItem,
       isActivePlugin = _usePlugins.isActivePlugin,
-      tabs = _usePlugins.tabs;
+      tabs = _usePlugins.tabs,
+      error = _usePlugins.error,
+      retry = _usePlugins.retry,
+      errorFallback = _usePlugins.errorFallback;
 
+  var isEditing = !!initUrl;
+  var selectedItem = items === null || items === void 0 ? void 0 : items[selectedIndex];
+  var isSelectedItem = (selectedItem === null || selectedItem === void 0 ? void 0 : selectedItem.url) === url;
   useLayoutEffect(function () {
     if (onContentResize) {
       onContentResize();
@@ -147,15 +165,15 @@ function LinkPicker(_ref) {
     dispatch(_defineProperty({}, field, ''));
   }, []);
   var handleMouseEnterResultItem = useCallback(function (objectId) {
-    var index = findIndex(items, function (item) {
+    var index = items === null || items === void 0 ? void 0 : items.findIndex(function (item) {
       return item.objectId === objectId;
     });
     dispatch({
-      activeIndex: index
+      activeIndex: index !== null && index !== void 0 ? index : -1
     });
   }, [items]);
   var handleMouseLeaveResultItem = useCallback(function (objectId) {
-    var index = findIndex(items, function (item) {
+    var index = items === null || items === void 0 ? void 0 : items.findIndex(function (item) {
       return item.objectId === objectId;
     }); // This is to avoid updating index that was set by other mouseenter event
 
@@ -166,6 +184,8 @@ function LinkPicker(_ref) {
     }
   }, [activeIndex, items]);
   var handleInsert = useCallback(function (url, title, inputType) {
+    var event = createAnalyticsEvent(createEventPayload('form.submitted.linkPicker', {}));
+    event.fire(ANALYTICS_CHANNEL);
     onSubmit(_objectSpread({
       url: url,
       displayText: displayText || null,
@@ -176,9 +196,9 @@ function LinkPicker(_ref) {
     }, inputType === 'manual' ? {
       rawUrl: state.url
     } : {}));
-  }, [displayText, onSubmit, state.url]);
+  }, [displayText, onSubmit, state.url, createAnalyticsEvent]);
   var handleSelected = useCallback(function (objectId) {
-    var selectedItem = items.find(function (item) {
+    var selectedItem = items === null || items === void 0 ? void 0 : items.find(function (item) {
       return item.objectId === objectId;
     });
 
@@ -189,9 +209,7 @@ function LinkPicker(_ref) {
     }
   }, [handleInsert, items]);
   var handleSubmit = useCallback(function () {
-    var selectedItem = items[selectedIndex];
-
-    if (isSelectedItem) {
+    if (isSelectedItem && selectedItem) {
       return handleInsert(selectedItem.url, selectedItem.name, 'typeAhead');
     }
 
@@ -204,18 +222,18 @@ function LinkPicker(_ref) {
     return dispatch({
       invalidUrl: true
     });
-  }, [handleInsert, isSelectedItem, items, selectedIndex, url]);
+  }, [handleInsert, isSelectedItem, selectedItem, url]);
   var linkPlaceHolder = isActivePlugin ? messages.placeholder : messages.linkPlaceholder;
-  var linkListTitle = url ? messages.titleResults : messages.titleRecentlyViewed;
+  var linkListTitle = (queryState === null || queryState === void 0 ? void 0 : (_queryState$query = queryState.query) === null || _queryState$query === void 0 ? void 0 : _queryState$query.length) !== 0 ? messages.titleResults : messages.titleRecentlyViewed;
   var insertButtonMsg = isEditing ? messages.saveButton : messages.insertButton;
-  var noResults = isActivePlugin && !isLoading && !items.length && !isSafeUrl(url);
+  var noResults = (items === null || items === void 0 ? void 0 : items.length) === 0 && !error;
   var screenReaderDescriptionId = 'search-recent-links-field-description';
   var linkSearchListId = 'link-picker-search-list';
   var ariaActiveDescendant = selectedIndex > -1 ? "link-search-list-item-".concat(selectedIndex) : ''; // Added workaround with a screen reader Announcer specifically for VoiceOver + Safari
   // as the Aria design pattern for combobox does not work in this case
   // for details: https://a11y-internal.atlassian.net/browse/AK-740
 
-  var screenReaderText = browser.safari && getScreenReaderText(items, selectedIndex, intl);
+  var screenReaderText = browser.safari && getScreenReaderText(items !== null && items !== void 0 ? items : [], selectedIndex, intl);
   var searchIcon = isActivePlugin && jsx("span", {
     css: searchIconStyles,
     "data-testid": testIds.searchIcon
@@ -267,7 +285,7 @@ function LinkPicker(_ref) {
     onSubmit: handleSubmit,
     onKeyDown: handleKeyDown,
     onChange: handleChangeText
-  }), tabs.length > 0 && jsx("div", {
+  }), queryState && jsx(Fragment, null, tabs.length > 0 && jsx("div", {
     css: tabsWrapperStyles
   }, jsx(Tabs, {
     id: testIds.tabList,
@@ -285,7 +303,7 @@ function LinkPicker(_ref) {
       key: tab.tabTitle,
       testId: testIds.tabItem
     }, tab.tabTitle);
-  })))), !!items.length && jsx("div", {
+  })))), !!(items !== null && items !== void 0 && items.length) && jsx("div", {
     css: listTitleStyles,
     id: testIds.resultListTitle,
     "data-testid": testIds.resultListTitle
@@ -293,7 +311,7 @@ function LinkPicker(_ref) {
     id: "fabric.smartcard.linkpicker.suggested.results"
   }, url && jsx(FormattedMessage, _extends({}, messages.searchLinkResults, {
     values: {
-      count: items.length
+      count: (_items$length = items === null || items === void 0 ? void 0 : items.length) !== null && _items$length !== void 0 ? _items$length : 0
     },
     "aria-live": "polite",
     "aria-atomic": "true"
@@ -302,18 +320,34 @@ function LinkPicker(_ref) {
     ariaControls: "fabric.smartcard.linkpicker.suggested.results",
     id: linkSearchListId,
     role: "listbox",
-    items: items,
+    items: items !== null && items !== void 0 ? items : [],
     isLoading: isLoading,
     selectedIndex: selectedIndex,
     activeIndex: activeIndex,
     onSelect: handleSelected,
     onMouseEnter: handleMouseEnterResultItem,
     onMouseLeave: handleMouseLeaveResultItem
-  }), noResults && jsx(LinkSearchNoResults, {
+  }), error && ((_errorFallback = errorFallback === null || errorFallback === void 0 ? void 0 : errorFallback(error, retry)) !== null && _errorFallback !== void 0 ? _errorFallback : jsx(LinkSearchError, {
+    testId: testIds.searchError,
+    header: intl.formatMessage(messages.searchErrorHeader),
+    description: jsx(FormattedMessage, _extends({}, messages.searchErrorDescription, {
+      values: {
+        a: function a(label) {
+          return jsx(Button, {
+            appearance: "link",
+            spacing: "none",
+            href: CONTACT_SUPPORT_LINK,
+            target: "_blank",
+            rel: "noopener noreferrer"
+          }, label);
+        }
+      }
+    }))
+  })), noResults && jsx(LinkSearchNoResults, {
     testId: testIds.emptyResultPage,
     header: intl.formatMessage(messages.noResults),
     description: intl.formatMessage(messages.noResultsDescription)
-  }), jsx(FormFooter, {
+  })), jsx(FormFooter, {
     align: "end"
   }, jsx(ButtonGroup, null, jsx(Button, {
     appearance: "default",
@@ -340,17 +374,4 @@ function getScreenReaderText(items, selectedIndex, intl) {
     var formattedDate = [date === null || date === void 0 ? void 0 : date.pageAction, date === null || date === void 0 ? void 0 : date.dateString, date === null || date === void 0 ? void 0 : date.timeSince].filter(Boolean).join(' ');
     return [name, container, formattedDate].filter(Boolean).join(', ');
   }
-}
-
-function findIndex(array, predicate) {
-  var index = -1;
-  array.some(function (item, i) {
-    if (predicate(item)) {
-      index = i;
-      return true;
-    }
-
-    return false;
-  });
-  return index;
 }

package/dist/esm/ui/link-picker/link-search-error/index.js

@@ -0,0 +1,14 @@
+import _extends from "@babel/runtime/helpers/extends";
+import React from 'react';
+import EmptyState from '@atlaskit/empty-state';
+import GenericErrorSVG from '../../../common/generic-error-svg';
+
+var LinkSearchError = function LinkSearchError(props) {
+  return /*#__PURE__*/React.createElement(EmptyState, _extends({}, props, {
+    renderImage: function renderImage() {
+      return /*#__PURE__*/React.createElement(GenericErrorSVG, null);
+    }
+  }));
+};
+
+export default LinkSearchError;

package/dist/esm/ui/link-picker/messages.js

@@ -104,5 +104,15 @@ export var messages = defineMessages({
     id: 'fabric.linkPicker.button.save',
     defaultMessage: 'Save',
     description: 'Button to save edited link'
+  },
+  searchErrorHeader: {
+    id: 'fabric.linkPicker.search.error.heading',
+    defaultMessage: 'We’re having trouble loading data.',
+    description: 'Heading message shown when a search throws an error'
+  },
+  searchErrorDescription: {
+    id: 'fabric.linkPicker.search.error.description',
+    defaultMessage: 'Refresh the page, or contact <a>Atlassian Support</a> if this keeps happening.',
+    description: 'Describes possible actions when search throws an error'
   }
 });

package/dist/esm/ui/link-picker/url.js

@@ -64,11 +64,6 @@ var linkifyMatch = function linkifyMatch(text) {
 
 export var isSafeUrl = function isSafeUrl(url) {
   var urlTrimmed = url.trim();
-
-  if (urlTrimmed.length === 0) {
-    return true;
-  }
-
   return whitelistedURLPatterns.some(function (p) {
     return p.test(urlTrimmed);
   });

package/dist/esm/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/link-picker",
-	"version": "1.6.0",
+	"version": "1.7.1",
 	"sideEffects": false
 }

package/dist/types/analytics.codegen.d.ts

@@ -0,0 +1,20 @@
+/**
+ * THIS FILE WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
+ *
+ * Generates analytics utilities from the package analytics spec yaml
+ *
+ * @codegen <<SignedSource::0cc1b4d9c22b31491ded3e581114ab2c>>
+ * @codegenCommand yarn workspace @atlaskit/link-picker run codegen-analytics
+ */
+declare type FormSubmittedLinkPickerAttributesType = {};
+declare type AnalyticsEventAttributes = {
+    'form.submitted.linkPicker': FormSubmittedLinkPickerAttributesType;
+};
+declare function createEventPayload<K extends keyof AnalyticsEventAttributes>(eventKey: K, attributes: AnalyticsEventAttributes[K]): {
+    eventType: string;
+    actionSubject: string;
+    action: string;
+    actionSubjectId: string;
+    attributes: AnalyticsEventAttributes[K];
+};
+export default createEventPayload;

package/dist/types/common/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const ANALYTICS_CHANNEL = "media";
+export declare const COMPONENT_NAME = "LinkPicker";

package/dist/types/index.d.ts

@@ -1,3 +1,3 @@
 export { ComposedLinkPicker as LinkPicker } from './ui';
 export type { LinkPickerProps } from './ui/link-picker';
-export type { LinkInputType, LinkPickerPlugin, LinkPickerState, LinkSearchListItemData, } from './ui/types';
+export type { LinkInputType, LinkPickerPlugin, LinkPickerState, LinkSearchListItemData, LinkPickerPluginErrorFallback, } from './ui/types';

package/dist/types/services/use-plugins/index.d.ts

@@ -1,12 +1,13 @@
-import { PickerState } from '../../ui/link-picker';
-import { LinkPickerPlugin, LinkSearchListItemData } from '../../ui/types';
+import { LinkPickerPlugin, LinkPickerPluginErrorFallback, LinkPickerState, LinkSearchListItemData } from '../../ui/types';
 export interface LinkPickerPluginsService {
-    items: LinkSearchListItemData[];
+    items: LinkSearchListItemData[] | null;
     isLoading: boolean;
-    isSelectedItem: boolean;
     isActivePlugin: boolean;
     tabs: {
         tabTitle: string;
     }[];
+    error: unknown | null;
+    retry: () => void;
+    errorFallback?: LinkPickerPluginErrorFallback;
 }
-export declare function usePlugins(state: PickerState, plugins?: LinkPickerPlugin[]): LinkPickerPluginsService;
+export declare function usePlugins(state: LinkPickerState | null, activeTab: number, plugins?: LinkPickerPlugin[]): LinkPickerPluginsService;

package/dist/types/services/use-search-query/index.d.ts

@@ -0,0 +1,3 @@
+import { LinkPickerState } from '../../ui/types';
+import { PickerState } from '../../ui/link-picker';
+export declare function useSearchQuery(state: PickerState): LinkPickerState | null;

package/dist/types/ui/link-picker/index.d.ts

@@ -1,6 +1,7 @@
 import { jsx } from '@emotion/react';
 import { LinkInputType, LinkPickerPlugin } from '../types';
 export declare const RECENT_SEARCH_LIST_SIZE = 5;
+export declare const CONTACT_SUPPORT_LINK = "https://support.atlassian.com/contact/";
 export declare const testIds: {
     linkPicker: string;
     urlInputField: string;
@@ -17,6 +18,7 @@ export declare const testIds: {
     urlError: string;
     tabList: string;
     tabItem: string;
+    searchError: string;
 };
 interface Meta {
     /** Indicates how the link was picked. */

package/dist/types/ui/link-picker/link-search-error/index.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="react" />
+import { EmptyStateProps } from '@atlaskit/empty-state';
+declare const LinkSearchError: (props: EmptyStateProps) => JSX.Element;
+export default LinkSearchError;

package/dist/types/ui/link-picker/messages.d.ts

@@ -104,4 +104,14 @@ export declare const messages: {
         defaultMessage: string;
         description: string;
     };
+    searchErrorHeader: {
+        id: string;
+        defaultMessage: string;
+        description: string;
+    };
+    searchErrorDescription: {
+        id: string;
+        defaultMessage: string;
+        description: string;
+    };
 };

package/dist/types/ui/types.d.ts

@@ -1,4 +1,4 @@
-/// <reference types="react" />
+import { ReactNode } from 'react';
 import { MessageDescriptor } from 'react-intl-next';
 export declare type LinkInputType = 'manual' | 'typeAhead';
 export interface LinkSearchListItemData {
@@ -36,9 +36,12 @@ export interface ResolveResult {
     data: LinkSearchListItemData[];
 }
 export interface LinkPickerPlugin {
+    resolve: (state: LinkPickerState) => Promise<ResolveResult> | AsyncGenerator<ResolveResult, ResolveResult>;
     /** Uniquely identify the tab */
     tabKey?: string;
     /** Human-readable label for the plugin */
     tabTitle?: string;
-    resolve: (state: LinkPickerState) => Promise<ResolveResult> | AsyncGenerator<ResolveResult, ResolveResult>;
+    /** Render function to customise the UI that is displayed when an error occurs resolving results */
+    errorFallback?: LinkPickerPluginErrorFallback;
 }
+export declare type LinkPickerPluginErrorFallback = (error: unknown, retry: () => void) => ReactNode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlaskit/link-picker",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "Standalone link picker",
   "author": "Atlassian Pty Ltd",
   "publishConfig": {
@@ -26,7 +26,8 @@
     ".": "./src/index.ts"
   },
   "scripts": {
-    "ak-postbuild": "ls -d dist/* | grep -v dist/types | xargs -n 1 copyfiles -u 1 -V src/**/*.svg"
+    "ak-postbuild": "ls -d dist/* | grep -v dist/types | xargs -n 1 copyfiles -u 1 -V src/**/*.svg",
+    "codegen-analytics": "ts-node --project ../../../tsconfig.node.json ./scripts/build/codegen-analytics"
   },
   "dependencies": {
     "@atlaskit/analytics-next": "^8.3.1",
@@ -52,26 +53,31 @@
     "react-intl-next": "npm:react-intl@^5.18.1"
   },
   "devDependencies": {
+    "@af/codegen": "*",
     "@atlaskit/activity-provider": "^2.3.2",
     "@atlaskit/docs": "*",
-    "@atlaskit/link-test-helpers": "^1.3.0",
-    "@atlaskit/popup": "^1.3.5",
+    "@atlaskit/link-test-helpers": "^1.4.0",
+    "@atlaskit/popup": "^1.4.0",
     "@atlaskit/ssr": "*",
     "@atlaskit/toggle": "^12.4.0",
     "@atlaskit/visual-regression": "*",
     "@atlaskit/webdriver-runner": "*",
     "@atlassian/atlassian-frontend-prettier-config-1.0.0": "npm:@atlassian/atlassian-frontend-prettier-config@1.0.0",
-    "@atlassian/link-picker-atlassian-plugin": "^16.0.0",
-    "@atlassian/link-picker-plugins": "^3.0.0",
+    "@atlassian/link-picker-atlassian-plugin": "^17.0.0",
+    "@atlassian/link-picker-plugins": "^4.0.0",
+    "@atlassian/recent-work-client": "^1.5.0",
     "@atlassian/search-provider": "^2.3.0",
     "@testing-library/dom": "^7.7.3",
     "@testing-library/jest-dom": "^4.1.0",
     "@testing-library/react": "^8.0.1",
     "@testing-library/react-hooks": "^1.0.4",
     "@testing-library/user-event": "10.4.0",
+    "@types/js-yaml": "^3.12.5",
     "enzyme": "^3.10.0",
     "fetch-mock": "^8.0.0",
+    "js-yaml": "^3.13.1",
     "mockdate": "^3.0.2",
+    "prettier": "^2.1.1",
     "react-dom": "^16.8.0",
     "sinon": "^2.2.0",
     "typescript": "4.2.4"

package/report.api.md

@@ -1,36 +1,44 @@
-## API Report File for "@atlaskit/link-picker"
+## API Report File for "@atlaskit/link-picker".
 
-> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+> Do not edit this file. This report is auto-generated by [API Extractor](https://api-extractor.com/).
 
-```ts
-/// <reference types="react" />
+[Learn more about API reports](https://hello.atlassian.net/wiki/spaces/UR/pages/1825484529/Package+API+Reports)
 
+```ts
 import { MessageDescriptor } from 'react-intl-next';
 import { default as React_2 } from 'react';
-import { WithIntlProps } from 'react-intl-next';
-import { WrappedComponentProps } from 'react-intl-next';
+import { ReactNode } from 'react';
 
 export declare type LinkInputType = 'manual' | 'typeAhead';
 
-export declare const LinkPicker: React_2.FC<
-  WithIntlProps<WrappedComponentProps<'intl'> & LinkPickerProps>
-> & {
-  WrappedComponent: React_2.ComponentType<
-    WrappedComponentProps<'intl'> & LinkPickerProps
-  >;
-};
+export declare const LinkPicker: React_2.MemoExoticComponent<(
+  props: LinkPickerProps,
+) => JSX.Element>;
 
 export declare interface LinkPickerPlugin {
   resolve: (
     state: LinkPickerState,
   ) => Promise<ResolveResult> | AsyncGenerator<ResolveResult, ResolveResult>;
+  /** Uniquely identify the tab */
+  tabKey?: string;
+  /** Human-readable label for the plugin */
+  tabTitle?: string;
+  /** Render function to customise the UI that is displayed when an error occurs resolving results */
+  errorFallback?: LinkPickerPluginErrorFallback;
 }
 
+export declare type LinkPickerPluginErrorFallback = (
+  error: unknown,
+  retry: () => void,
+) => ReactNode;
+
 export declare interface LinkPickerProps {
   /** Callback to fire on form submission. */
   onSubmit: (arg: OnSubmitParameter) => void;
   /** Callback to fire when the cancel button is clicked. */
   onCancel: () => void;
+  /** Callback to fire when content is changed inside the link picker e.g. items, when loading, tabs */
+  onContentResize?: () => void;
   /** The url of the linked resource for editing. */
   url?: string;
   /** The desired text to be displayed alternatively to the title of the linked resource for editing. */