hooks.tsx 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644
  1. import type {Route, RouteComponentProps, RouteContextInterface} from 'react-router';
  2. import type {ChildrenRenderFn} from 'sentry/components/acl/feature';
  3. import type {Guide} from 'sentry/components/assistant/types';
  4. import {ButtonProps} from 'sentry/components/button';
  5. import type DateRange from 'sentry/components/organizations/timeRangeSelector/dateRange';
  6. import type SelectorItems from 'sentry/components/organizations/timeRangeSelector/selectorItems';
  7. import type SidebarItem from 'sentry/components/sidebar/sidebarItem';
  8. import type {Group} from 'sentry/types';
  9. import {UseExperiment} from 'sentry/utils/useExperiment';
  10. import {UsageStatsOrganizationProps} from 'sentry/views/organizationStats/usageStatsOrg';
  11. import {RouteAnalyticsContext} from 'sentry/views/routeAnalyticsContextProvider';
  12. import type {NavigationItem, NavigationSection} from 'sentry/views/settings/types';
  13. import type {ExperimentKey} from './experiments';
  14. import type {Integration, IntegrationProvider} from './integrations';
  15. import type {Member, Organization} from './organization';
  16. import type {Project} from './project';
  17. import type {User} from './user';
  18. // XXX(epurkhiser): A Note about `_`.
  19. //
  20. // We add the `_: any` type int our hooks list to stop
  21. // typescript from doing too much type tightening. We should absolutely revisit
  22. // this in the future because all callbacks _should_ be allowed to be
  23. // functions, but doing so causes some unexpected issues and makes typescript
  24. // not happy. We still get a huge advantage of typing just by having each hook
  25. // type here however.
  26. /**
  27. * The Hooks type mapping is the master interface for all external Hooks into
  28. * the sentry frontend application.
  29. */
  30. export interface Hooks
  31. extends RouteHooks,
  32. ComponentHooks,
  33. CustomizationHooks,
  34. AnalyticsHooks,
  35. FeatureDisabledHooks,
  36. InterfaceChromeHooks,
  37. OnboardingHooks,
  38. SettingsHooks,
  39. FeatureSpecificHooks,
  40. ReactHooks,
  41. CallbackHooks {
  42. _: any;
  43. }
  44. export type HookName = keyof Hooks;
  45. /**
  46. * Route hooks.
  47. */
  48. export type RouteHooks = {
  49. 'routes:api': RoutesHook;
  50. 'routes:organization': RoutesHook;
  51. };
  52. /**
  53. * Component specific hooks for DateRange and SelectorItems
  54. * These components have plan specific overrides in getsentry
  55. */
  56. type DateRangeProps = React.ComponentProps<typeof DateRange>;
  57. type SelectorItemsProps = React.ComponentProps<typeof SelectorItems>;
  58. type DisabledMemberViewProps = RouteComponentProps<{orgId: string}, {}>;
  59. type MemberListHeaderProps = {
  60. members: Member[];
  61. organization: Organization;
  62. };
  63. type DisabledAppStoreConnectMultiple = {organization: Organization};
  64. type DisabledCustomSymbolSources = {organization: Organization};
  65. type DisabledMemberTooltipProps = {children: React.ReactNode};
  66. type DashboardHeadersProps = {organization: Organization};
  67. type ReplayGracePeriodAlertProps = {organization: Organization};
  68. type ReplayOnboardinCTAProps = {children: React.ReactNode; organization: Organization};
  69. type FirstPartyIntegrationAlertProps = {
  70. integrations: Integration[];
  71. hideCTA?: boolean;
  72. wrapWithContainer?: boolean;
  73. };
  74. type FirstPartyIntegrationAdditionalCTAProps = {
  75. integrations: Integration[];
  76. };
  77. type AttemptCloseAttemptProps = {
  78. handleRemoveAccount: () => void;
  79. organizationSlugs: string[];
  80. };
  81. type CodecovLinkProps = {
  82. organization: Organization;
  83. };
  84. type QualitativeIssueFeedbackProps = {
  85. group: Group;
  86. organization: Organization;
  87. };
  88. type GuideUpdateCallback = (nextGuide: Guide | null, opts: {dismissed?: boolean}) => void;
  89. /**
  90. * Component wrapping hooks
  91. */
  92. export type ComponentHooks = {
  93. 'component:codecov-integration-cta': () => React.ReactNode;
  94. 'component:codecov-integration-settings-link': () => React.ComponentType<CodecovLinkProps>;
  95. 'component:codecov-integration-stacktrace-link': () => React.ComponentType<CodecovLinkProps>;
  96. 'component:confirm-account-close': () => React.ComponentType<AttemptCloseAttemptProps>;
  97. 'component:dashboards-header': () => React.ComponentType<DashboardHeadersProps>;
  98. 'component:disabled-app-store-connect-multiple': () => React.ComponentType<DisabledAppStoreConnectMultiple>;
  99. 'component:disabled-custom-symbol-sources': () => React.ComponentType<DisabledCustomSymbolSources>;
  100. 'component:disabled-member': () => React.ComponentType<DisabledMemberViewProps>;
  101. 'component:disabled-member-tooltip': () => React.ComponentType<DisabledMemberTooltipProps>;
  102. 'component:enhanced-org-stats': () => React.ComponentType<UsageStatsOrganizationProps>;
  103. 'component:first-party-integration-additional-cta': () => React.ComponentType<FirstPartyIntegrationAdditionalCTAProps>;
  104. 'component:first-party-integration-alert': () => React.ComponentType<FirstPartyIntegrationAlertProps>;
  105. 'component:header-date-range': () => React.ComponentType<DateRangeProps>;
  106. 'component:header-selector-items': () => React.ComponentType<SelectorItemsProps>;
  107. 'component:issue-priority-feedback': () => React.ComponentType<QualitativeIssueFeedbackProps>;
  108. 'component:member-list-header': () => React.ComponentType<MemberListHeaderProps>;
  109. 'component:org-stats-banner': () => React.ComponentType<DashboardHeadersProps>;
  110. 'component:replay-beta-grace-period-alert': () => React.ComponentType<ReplayGracePeriodAlertProps>;
  111. 'component:replay-feedback-button': () => React.ComponentType<{}>;
  112. 'component:replay-onboarding-cta': () => React.ComponentType<ReplayOnboardinCTAProps>;
  113. 'component:superuser-access-category': React.FC<any>;
  114. };
  115. /**
  116. * Customization hooks are advanced hooks that return render-prop style
  117. * components the allow for specific customizations of components.
  118. *
  119. * These are very similar to the component wrapping hooks
  120. */
  121. export type CustomizationHooks = {
  122. 'integrations:feature-gates': IntegrationsFeatureGatesHook;
  123. 'member-invite-button:customization': InviteButtonCustomizationHook;
  124. 'member-invite-modal:customization': InviteModalCustomizationHook;
  125. };
  126. /**
  127. * Analytics / tracking / and operational metrics backend hooks.
  128. */
  129. export type AnalyticsHooks = {
  130. // TODO(scefali): Below are deprecated and should be replaced
  131. 'analytics:event': LegacyAnalyticsEvent;
  132. 'analytics:init-user': AnalyticsInitUser;
  133. 'analytics:log-experiment': AnalyticsLogExperiment;
  134. 'analytics:track-adhoc-event': AnalyticsTrackAdhocEvent;
  135. 'analytics:track-event': AnalyticsTrackEvent;
  136. 'analytics:track-event-v2': AnalyticsTrackEventV2;
  137. 'metrics:event': MetricsEvent;
  138. };
  139. /**
  140. * feature-disabled:<feature-flag> hooks return components that will be
  141. * rendered in place for Feature components when the feature is not enabled.
  142. */
  143. export type FeatureDisabledHooks = {
  144. 'feature-disabled:alert-wizard-performance': FeatureDisabledHook;
  145. 'feature-disabled:alerts-page': FeatureDisabledHook;
  146. 'feature-disabled:codecov-integration-setting': FeatureDisabledHook;
  147. 'feature-disabled:custom-inbound-filters': FeatureDisabledHook;
  148. 'feature-disabled:dashboards-edit': FeatureDisabledHook;
  149. 'feature-disabled:dashboards-page': FeatureDisabledHook;
  150. 'feature-disabled:dashboards-sidebar-item': FeatureDisabledHook;
  151. 'feature-disabled:data-forwarding': FeatureDisabledHook;
  152. 'feature-disabled:discard-groups': FeatureDisabledHook;
  153. 'feature-disabled:discover-page': FeatureDisabledHook;
  154. 'feature-disabled:discover-saved-query-create': FeatureDisabledHook;
  155. 'feature-disabled:discover-sidebar-item': FeatureDisabledHook;
  156. 'feature-disabled:discover2-page': FeatureDisabledHook;
  157. 'feature-disabled:discover2-sidebar-item': FeatureDisabledHook;
  158. 'feature-disabled:events-page': FeatureDisabledHook;
  159. 'feature-disabled:events-sidebar-item': FeatureDisabledHook;
  160. 'feature-disabled:grid-editable-actions': FeatureDisabledHook;
  161. 'feature-disabled:incidents-sidebar-item': FeatureDisabledHook;
  162. 'feature-disabled:open-discover': FeatureDisabledHook;
  163. 'feature-disabled:open-in-discover': FeatureDisabledHook;
  164. 'feature-disabled:performance-new-project': FeatureDisabledHook;
  165. 'feature-disabled:performance-page': FeatureDisabledHook;
  166. 'feature-disabled:performance-quick-trace': FeatureDisabledHook;
  167. 'feature-disabled:performance-sidebar-item': FeatureDisabledHook;
  168. 'feature-disabled:profiling-page': FeatureDisabledHook;
  169. 'feature-disabled:profiling-sidebar-item': FeatureDisabledHook;
  170. 'feature-disabled:project-performance-score-card': FeatureDisabledHook;
  171. 'feature-disabled:project-selector-all-projects': FeatureDisabledHook;
  172. 'feature-disabled:project-selector-checkbox': FeatureDisabledHook;
  173. 'feature-disabled:rate-limits': FeatureDisabledHook;
  174. 'feature-disabled:relay': FeatureDisabledHook;
  175. 'feature-disabled:replay-sidebar-item': FeatureDisabledHook;
  176. 'feature-disabled:sso-basic': FeatureDisabledHook;
  177. 'feature-disabled:sso-saml2': FeatureDisabledHook;
  178. 'feature-disabled:starfish-view': FeatureDisabledHook;
  179. 'feature-disabled:trace-view-link': FeatureDisabledHook;
  180. };
  181. /**
  182. * Interface chrome hooks.
  183. */
  184. export type InterfaceChromeHooks = {
  185. footer: GenericComponentHook;
  186. 'help-modal:footer': HelpModalFooterHook;
  187. 'organization:header': OrganizationHeaderComponentHook;
  188. 'sidebar:bottom-items': SidebarBottomItemsHook;
  189. 'sidebar:help-menu': GenericOrganizationComponentHook;
  190. 'sidebar:item-label': SidebarItemLabelHook;
  191. 'sidebar:organization-dropdown-menu': GenericOrganizationComponentHook;
  192. 'sidebar:organization-dropdown-menu-bottom': GenericOrganizationComponentHook;
  193. };
  194. /**
  195. * Onboarding experience hooks
  196. */
  197. export type OnboardingHooks = {
  198. 'onboarding-wizard:skip-help': GenericOrganizationComponentHook;
  199. 'onboarding:block-hide-sidebar': () => boolean;
  200. 'onboarding:extra-chrome': GenericComponentHook;
  201. 'onboarding:targeted-onboarding-header': (opts: {source: string}) => React.ReactNode;
  202. };
  203. /**
  204. * Settings navigation hooks.
  205. */
  206. export type SettingsHooks = {
  207. 'settings:api-navigation-config': SettingsItemsHook;
  208. 'settings:organization-navigation': OrganizationSettingsHook;
  209. 'settings:organization-navigation-config': SettingsConfigHook;
  210. };
  211. /**
  212. * Feature Specific Hooks
  213. */
  214. export interface FeatureSpecificHooks extends SpendVisibilityHooks {}
  215. /**
  216. * Hooks related to Spend Visibitlity
  217. * (i.e. Per-Project Spike Protection + Spend Allocations)
  218. */
  219. export type SpendVisibilityHooks = {
  220. 'spend-visibility:spike-protection-project-settings': GenericProjectComponentHook;
  221. };
  222. /**
  223. * Hooks that are actually React Hooks as well
  224. */
  225. export type ReactHooks = {
  226. 'react-hook:route-activated': (
  227. props: RouteContextInterface
  228. ) => React.ContextType<typeof RouteAnalyticsContext>;
  229. 'react-hook:use-button-tracking': (props: ButtonProps) => () => void;
  230. 'react-hook:use-experiment': UseExperiment;
  231. };
  232. /**
  233. * Callback hooks.
  234. * These hooks just call a function that has no return value
  235. * and perform some sort of callback logic
  236. */
  237. type CallbackHooks = {
  238. 'callback:on-guide-update': GuideUpdateCallback;
  239. };
  240. /**
  241. * Renders a React node with no props
  242. */
  243. type GenericComponentHook = () => React.ReactNode;
  244. /**
  245. * A route hook provides an injection point for a list of routes.
  246. */
  247. type RoutesHook = () => Route[];
  248. /**
  249. * Receives an organization object and should return a React node.
  250. */
  251. type GenericOrganizationComponentHook = (opts: {
  252. organization: Organization;
  253. }) => React.ReactNode;
  254. /**
  255. * Receives a project object and should return a React node.
  256. */
  257. type GenericProjectComponentHook = (opts: {project: Project}) => React.ReactNode;
  258. // TODO(ts): We should correct the organization header hook to conform to the
  259. // GenericOrganizationComponentHook, passing org as a prop object, not direct
  260. // as the only argument.
  261. type OrganizationHeaderComponentHook = (org: Organization) => React.ReactNode;
  262. /**
  263. * A FeatureDisabledHook returns a react element when a feature is not enabled.
  264. */
  265. type FeatureDisabledHook = (opts: {
  266. /**
  267. * Children can either be a node, or a function that accepts a renderDisabled prop containing
  268. * a function/component to render when the feature is not enabled.
  269. */
  270. children: React.ReactNode | ChildrenRenderFn;
  271. /**
  272. * The list of features that are controlled by this hook.
  273. */
  274. features: string[];
  275. /**
  276. * Weather the feature is or is not enabled.
  277. */
  278. hasFeature: boolean;
  279. /**
  280. * The organization that is associated to this feature.
  281. */
  282. organization: Organization;
  283. /**
  284. * The project that is associated to this feature.
  285. */
  286. project?: Project;
  287. }) => React.ReactNode;
  288. /**
  289. * Called when the app is mounted.
  290. */
  291. type AnalyticsInitUser = (user: User) => void;
  292. /**
  293. * Trigger analytics tracking in the hook store.
  294. */
  295. type AnalyticsTrackEvent = (opts: {
  296. /**
  297. * Arbitrary data to track
  298. */
  299. [key: string]: any;
  300. /**
  301. * The key used to identify the event.
  302. */
  303. eventKey: string;
  304. /**
  305. * The English string used as the name of the event.
  306. */
  307. eventName: string;
  308. organization_id: string | number | null;
  309. }) => void;
  310. /**
  311. * Trigger analytics tracking in the hook store.
  312. */
  313. type AnalyticsTrackEventV2 = (
  314. data: {
  315. /**
  316. * Arbitrary data to track
  317. */
  318. [key: string]: any;
  319. /**
  320. * The Reload event key.
  321. */
  322. eventKey: string;
  323. /**
  324. * The Amplitude event name. Set to null if event should not go to Amplitude.
  325. */
  326. eventName: string | null;
  327. /**
  328. * Organization to pass in. If full org object not available, pass in just the Id.
  329. * If no org, pass in null.
  330. */
  331. organization: Organization | string | null;
  332. },
  333. options?: {
  334. /**
  335. * An arbitrary function to map the parameters to new parameters
  336. */
  337. mapValuesFn?: (params: Record<string, any>) => Record<string, any>;
  338. /**
  339. * If true, starts an analytics session. This session can be used
  340. * to construct funnels. The start of the funnel should have
  341. * startSession set to true.
  342. */
  343. startSession?: boolean;
  344. /**
  345. * Optional unix timestamp
  346. */
  347. time?: number;
  348. }
  349. ) => void;
  350. /**
  351. * Trigger ad hoc analytics tracking in the hook store.
  352. */
  353. type AnalyticsTrackAdhocEvent = (opts: {
  354. /**
  355. * Arbitrary data to track
  356. */
  357. [key: string]: any;
  358. /**
  359. * The key used to identify the event.
  360. */
  361. eventKey: string;
  362. }) => void;
  363. /**
  364. * Trigger experiment observed logging.
  365. */
  366. type AnalyticsLogExperiment = (opts: {
  367. /**
  368. * The experiment key
  369. */
  370. key: ExperimentKey;
  371. /**
  372. * The organization. Must be provided for organization experiments.
  373. */
  374. organization?: Organization;
  375. }) => void;
  376. /**
  377. * Trigger analytics tracking in the hook store.
  378. *
  379. * Prefer using `analytics:track-event` or `analytics:track-adhock-event`.
  380. *
  381. * @deprecated This is the legacy interface.
  382. */
  383. type LegacyAnalyticsEvent = (
  384. /**
  385. * The key used to identify the event.
  386. */
  387. name: string,
  388. /**
  389. * Arbitrary data to track
  390. */
  391. data: {[key: string]: any}
  392. ) => void;
  393. /**
  394. * Trigger recording a metric in the hook store.
  395. */
  396. type MetricsEvent = (
  397. /**
  398. * Metric name
  399. */
  400. name: string,
  401. /**
  402. * Value to record for this metric
  403. */
  404. value: number,
  405. /**
  406. * An additional tags object
  407. */
  408. tags?: object
  409. ) => void;
  410. /**
  411. * Provides additional navigation components
  412. */
  413. type OrganizationSettingsHook = (organization: Organization) => React.ReactElement;
  414. /**
  415. * Provides additional setting configurations
  416. */
  417. type SettingsConfigHook = (organization: Organization) => NavigationSection;
  418. /**
  419. * Provides additional setting navigation items
  420. */
  421. type SettingsItemsHook = (organization?: Organization) => NavigationItem[];
  422. /**
  423. * Each sidebar label is wrapped with this hook, to allow sidebar item
  424. * augmentation.
  425. */
  426. type SidebarItemLabelHook = () => React.ComponentType<{
  427. /**
  428. * The item label being wrapped
  429. */
  430. children: React.ReactNode;
  431. /**
  432. * The key of the item label currently being rendered. If no id is provided
  433. * the hook will have no effect.
  434. */
  435. id?: string;
  436. }>;
  437. type SidebarProps = Pick<
  438. React.ComponentProps<typeof SidebarItem>,
  439. 'orientation' | 'collapsed' | 'hasPanel'
  440. >;
  441. /**
  442. * Returns an additional list of sidebar items.
  443. */
  444. type SidebarBottomItemsHook = (
  445. opts: SidebarProps & {organization: Organization}
  446. ) => React.ReactNode;
  447. /**
  448. * Provides augmentation of the help modal footer
  449. */
  450. type HelpModalFooterHook = (opts: {
  451. closeModal: () => void;
  452. organization: Organization;
  453. }) => React.ReactNode;
  454. /**
  455. * The DecoratedIntegrationFeature differs from the IntegrationFeature as it is
  456. * expected to have been transformed into marked up content.
  457. */
  458. type DecoratedIntegrationFeature = {
  459. /**
  460. * Marked up description
  461. */
  462. description: React.ReactNode;
  463. featureGate: string;
  464. };
  465. type IntegrationFeatureGroup = {
  466. /**
  467. * The list of features within this group
  468. */
  469. features: DecoratedIntegrationFeature[];
  470. /**
  471. * Weather the group has all of the features enabled within this group
  472. * or not.
  473. */
  474. hasFeatures: boolean;
  475. };
  476. type FeatureGateSharedProps = {
  477. /**
  478. * The list of features, typically this is provided by the backend.
  479. */
  480. features: DecoratedIntegrationFeature[];
  481. /**
  482. * Organization of the integration we're querying feature gate details for.
  483. */
  484. organization: Organization;
  485. };
  486. type IntegrationFeaturesProps = FeatureGateSharedProps & {
  487. /**
  488. * The children function which will be provided with gating details.
  489. */
  490. children: (opts: {
  491. /**
  492. * Is the integration disabled for installation because of feature gating?
  493. */
  494. disabled: boolean;
  495. /**
  496. * The translated reason that the integration is disabled.
  497. */
  498. disabledReason: React.ReactNode;
  499. /**
  500. * Features grouped based on specific gating criteria (for example, in
  501. * sentry.io this is features grouped by plans).
  502. */
  503. gatedFeatureGroups: IntegrationFeatureGroup[];
  504. /**
  505. * This is the list of features which have *not* been gated in any way.
  506. */
  507. ungatedFeatures: DecoratedIntegrationFeature[];
  508. }) => React.ReactElement;
  509. };
  510. type IntegrationFeatureListProps = FeatureGateSharedProps & {
  511. provider: Pick<IntegrationProvider, 'key'>;
  512. };
  513. /**
  514. * The integration features gate hook provides components to customize
  515. * integration feature lists.
  516. */
  517. type IntegrationsFeatureGatesHook = () => {
  518. /**
  519. * This component renders the list of integration features.
  520. */
  521. FeatureList: React.ComponentType<IntegrationFeatureListProps>;
  522. /**
  523. * This is a render-prop style component that given a set of integration
  524. * features will call the children function with gating details about the
  525. * features.
  526. */
  527. IntegrationFeatures: React.ComponentType<IntegrationFeaturesProps>;
  528. };
  529. /**
  530. * Invite Button customization allows for a render-props component to replace
  531. * or intercept props of the button element.
  532. */
  533. type InviteButtonCustomizationHook = () => React.ComponentType<{
  534. children: (opts: {
  535. /**
  536. * Whether the Invite Members button is active or not
  537. */
  538. disabled: boolean;
  539. onTriggerModal: () => void;
  540. }) => React.ReactElement;
  541. onTriggerModal: () => void;
  542. organization: Organization;
  543. }>;
  544. /**
  545. * Invite Modal customization allows for a render-prop component to add
  546. * additional react elements into the modal, and add invite-send middleware.
  547. */
  548. type InviteModalCustomizationHook = () => React.ComponentType<{
  549. children: (opts: {
  550. /**
  551. * Indicates that the modal's send invites button should be enabled and
  552. * invites may currently be sent.
  553. */
  554. canSend: boolean;
  555. /**
  556. * Trigger sending invites
  557. */
  558. sendInvites: () => void;
  559. /**
  560. * Additional react elements to render in the header of the modal, just
  561. * under the description.
  562. */
  563. headerInfo?: React.ReactNode;
  564. }) => React.ReactElement;
  565. /**
  566. * When the children's sendInvites renderProp is called, this will also be
  567. * triggered.
  568. */
  569. onSendInvites: () => void;
  570. /**
  571. * The organization that members will be invited to.
  572. */
  573. organization: Organization;
  574. /**
  575. * Indicates if clicking 'send invites' will immediately send invites, or
  576. * would just create invite requests.
  577. */
  578. willInvite: boolean;
  579. }>;